Managing Configuration Source Providers

This topic describes how to 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 InfrastructureResource Manager to GitHub and GitLab.

  • Your GitHub or GitLab server must be accessible over the Internet by Oracle Cloud Infrastructure IP addresses. (This accessibility requirement does not apply to GitLab.com.) 
    • 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.
    • 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).
    • Enable network ingress rules on the VCN where your GitHub or GitLab server is deployed to allow access from Oracle Cloud Infrastructure IP addresses.
  • You must have GitHub or GitLab admin or owner permissions for the repository.
  • 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.
  • You must have Resource Manager permissions required for your task:
    • 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 Policies for Managing Resources Used with Resource Manager.

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).

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.
    • 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 Details 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 Configuration Source Provider.
  5. In the Edit Configuration Source Provider dialog box, update property values as needed.

  6. Click Save.
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 Configuration Source Provider 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.