Managing Configuration Source Providers

Create, edit, and delete configuration source providers for remote Terraform configurations.

Prerequisites for connecting to GitHub and GitLab

Following are the prerequisites to connect Oracle Cloud Infrastructure Resource Manager to GitHub and GitLab.

  • Private Git server: Network information required to set up a private endpoint for use with the configuration source provider. For more information, see Private Git Server.
  • Public Git server: Must be accessible over the Internet using a public IP address. (This accessibility requirement does not apply to GitLab.com.) 
  • Resolvable URL: Make sure Resource Manager can resolve your GitHub or GitLab URL. Make sure that your GitHub or GitLab server is deployed with a well-known root certificate, such as digicert, so that Oracle Cloud Infrastructure can trust its endpoint.
  • GitHub APIs: Your GitHub server must use GitHub APIs. An example of a GitHub server that doesn't meet this prerequisite is an Azure native GitHub solution (example).
  • Network configuration for IP addresses: Configure your network to allow access from Oracle Cloud Infrastructure IP address ranges. Ensure that you include ranges for all relevant services, including the Oracle Services Network (tag: OSN).
  • Ingress rules: Enable network ingress rules on the VCN where your GitHub or GitLab server is deployed to allow access from Oracle Cloud Infrastructure IP addresses.
  • Repository permissions: You must have GitHub or GitLab admin or owner permissions for the repository.
  • Personal Access Token: You must have a Personal Access Token (PAT) to your GitHub or GitLab server. To create a PAT, see the relevant guidance and documentation:
    Note

    Resource Manager reads the customer's repository content but does not push changes to the repository.
  • Resource Manager permissions:
    • To create a configuration source provider, you need manage orm-config-source-providers.
    • To create a stack with an existing configuration source provider, you need manage orm-stacks and read orm-config-source-providers.

      For more information, see IAM Policies.

For troubleshooting information, see GitHub and GitLab Connection Issues.

Required IAM Policy

To manage configuration source providers, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

Important

Policies for managing Oracle Cloud Infrastructure resources are also required for Resource Manager operations that access resources. For example, running an apply job on a stack that includes Compute instances and subnets requires policies that grant you permissions for those resource types, in the compartments where you want to provision the resources. To see examples of policies for managing Oracle Cloud Infrastructure resources, see Common Policies.

If you're new to policies, see Getting Started with Policies and Common Policies.

Administrators: For common policies that give groups access to Resource Manager resources, see Manage Configuration Source Providers (Securing Resource Manager).

Certificates

To access a private Git server, make its associated SSL certificate available in the Oracle Cloud Infrastructure Certificates service.

For more information about the Certificates service, see Certificates.

After the certificate is in the Certificates service, you can select it along with a private endpoint when you create the configuration source provider.

To import an existing certificate

  1. Get the certificate information for your private Git server.
    1. Install the OpenSSL command line application.

      For Linux, run: sudo yum install openssl

      For MacOS, run: brew install openssl

      For Windows, download the openssl binary from Win32/Win64 OpenSSL and configure the environment.

    2. Get the certificate chain.

      Run the following command (replace $SERVERNAME with your server URL; replace $PORT with your server's TCP port.):

      openssl s_client -connect $SERVERNAME:$PORT -servername $SERVERNAME -showcerts 2>&1 < /dev/null | sed -n '/-----BEGIN/,/-----END/p' > certChain.pem
    3. Get the server certificate.

      Run the following command (replace $SERVERNAME with your server URL; replace $PORT with your server's TCP port.):

      echo -n | openssl s_client -connect $SERVERNAME:$PORT -servername $SERVERNAME | openssl x509 > $SERVERNAME.pem
    4. Get the private key.

      Example source of private key from NGINX Gitlab Server (/etc/gitlab/gitlab.rb):

      nginx['ssl_certificate_key'] = <Path_to_PRIVATE_KEY>
  2. Import the certificate.

    See Importing a Certificate.

    After the certificate is in the Certificates service, you can select it along with a private endpoint when you create the configuration source provider.

Using the Console

To create a configuration source provider
Important

To connect to GitHub or GitLab, you must use a Personal Access Token. See Prerequisites for connecting to GitHub and GitLab.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Configuration Source Providers.

  2. Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click Create Configuration Source Provider.
  4. In the Create Configuration Source Provider panel, do the following.
    • Type a Name for your configuration source provider. Avoid entering confidential information.
    • Type a Description.
    • Select the Compartment where you want to create the configuration source provider.
    • To use a private endpoint for access to the Git server, do the following.
      1. Click Private Endpoint.

        For more information about private endpoints for private Git servers, see Private Git Server.

      2. Select or create a Private Endpoint.

        To select a private endpoint in a different compartment, click Change Compartment.

      3. (Optional) Select a SSL certificate.

        To select a certificate in a different compartment, click Change Compartment.

        For more information about SSL certificates, see Certificates.

    • Select the Type of configuration source provider you want. Choose from the following options.

    • Paste the Server URL.

      Example URLs:

      Product Example URL
      GitHub Enterprise Cloud https://github.com/org-name
      GitHub Enterprise Server https://hostname/api/v3
      GitHub Free for Organization https://github.com/org-name
      GitHub Free for User Accounts https://github.com
      GitHub team https://github.com/team-name
      GitLab.com product https://gitlab.com/
      GitLab installation (relative URL) https://example.com/gitlab
      GitLab installation (subdomain) https://gitlab.example.com/
    • Paste the Personal Access Token.
    • To tag the new configuration source provider, click Show Advanced Options and add your tag.
  5. Click Create.

    Note

    To confirm that Resource Manager can access the server URL using the provided Personal Access Token (PAT), click Validate connection on the detail page for your configuration source provider. For steps, see To confirm accessibility of a configuration source provider.
To confirm accessibility of a configuration source provider
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Configuration Source Providers.

  2. Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the configuration source provider that you want.

  4. On the Configuration Source Provider Information page, click Validate connection.

    This option is located on the Configuration Source Provider Information tab, to the right of Server URL.

    A message appears indicating whether Resource Manager can access the server URL using the provided Personal Access Token (PAT).

    For troubleshooting information, see GitHub and GitLab Connection Issues.

To edit a configuration source provider
Note

To confirm that Resource Manager can access the server URL using the provided Personal Access Token (PAT), click Validate connection on the detail page for your configuration source provider. For steps, see To confirm accessibility of a configuration source provider.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Configuration Source Providers.

  2. Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the configuration source provider that you want to edit.
  4. Click Edit.
  5. In the Edit Configuration Source Provider dialog box, update property values as needed.

  6. Click Save Changes.
To delete a configuration source provider
Note

A configuration source provider cannot be deleted if it is associated with a stack. To remove the association from the stack, edit the stack.
  1. Open the navigation menu and click Developer Services. Under Resource Manager, click Configuration Source Providers.

  2. Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the name of the configuration source provider that you want to delete.
  4. Click Delete and then confirm the action.

Using the CLI

This section provides basic sample CLI commands for managing stacks and jobs. For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.

For a walk-through using CLI for cloud provisioning in a CI/CD pipeline, see IaC in the Cloud: Integrating Terraform and Resource Manager into your CI/CD Pipeline - Building With the OCI CLI.

To create a configuration source provider
Important

To connect to GitHub or GitLab, you must use a Personal Access Token. See Prerequisites for connecting to GitHub and GitLab.
Choose the option for the provider type you want:
  • GitHub:

    Open a command prompt and run resource-manager configuration-source-provider create-github-access-token-provider to create a GitHub configuration source provider: 

    oci resource-manager stack create-github-access-token-provider --api-endpoint <github_url> --access-token <personal_access_token> --compartment-id <compartment_OCID> --display-name "<friendly_name>" --description "<description>"

    For example: 

    oci resource-manager stack create-github-access-token-provider --api-endpoint https://api.github.com/ --access-token token --compartment-id ocid1.tenancy.oc1..uniqueid --display-name "My Configuration Source Provider" --description "Department 80"
  • GitLab:

    Open a command prompt and run resource-manager configuration-source-provider create-gitlab-access-token-provider to create a GitLab configuration source provider: 

    oci resource-manager stack create-gitlab-access-token-provider --api-endpoint <gitlab_url> --access-token <personal_access_token> --compartment-id <compartment_OCID> --display-name "<friendly_name>" --description "<description>"

    For example: 

    oci resource-manager stack create-gitlab-access-token-provider --api-endpoint https://gitlab.com/api/v3/ --access-token token --compartment-id ocid1.tenancy.oc1..uniqueid --display-name "My Configuration Source Provider" --description "Department 80"

For a complete list of flags and options available for CLI commands, see CLI Help.

To update a configuration source provider
Choose the option for the provider type you want:
  • GitHub:

    Open a command prompt and run resource-manager configuration-source-provider update-github-access-token-provider to edit the specified configuration source provider: 

    oci resource-manager stack update-github-access-token-provider --configuration-source-provider-id <configuration_source_provider_OCID> --api-endpoint <github_url> --access-token <personal_access_token> --display-name "<friendly_name>" --description "<description>"

    For example: 

    oci resource-manager stack update-github-access-token-provider --configuration-source-provider-id ocid.ormconfigsourceprovider.oc1..uniqueid --description "Department 99"
  • GitLab:

    Open a command prompt and run resource-manager configuration-source-provider update-gitlab-access-token-provider to edit the specified configuration source provider: 

    oci resource-manager stack update-gitlab-access-token-provider --configuration-source-provider-id <configuration_source_provider_OCID> --api-endpoint <gitlab_url> --access-token <personal_access_token> --display-name "<friendly_name>" --description "<description>"

    For example: 

    oci resource-manager stack update-gitlab-access-token-provider --configuration-source-provider-id ocid.ormconfigsourceprovider.oc1..uniqueid --description "Department 99"

For a complete list of flags and options available for CLI commands, see CLI Help.

To delete a configuration source provider
Note

A configuration source provider cannot be deleted if it is associated with a stack. To remove the association from the stack, edit the stack.

Open a command prompt and run resource-manager configuration-source-provider delete to delete the specified configuration source provider: 

oci resource-manager configuration-source-provider delete --config-source-configuration-source-provider-id <configuration_source_provider_OCID>

For a complete list of flags and options available for CLI commands, see CLI Help.