Connecting DNS providers

With IBM Cloud® Secrets Manager, you can connect to a DNS provider by adding a configuration to your instance.

A DNS provider is the service that is used to add and manage domains for apps or services. By adding a DNS configuration, you can specify the DNS service to use for domain validation when you order certificates through Secrets Manager.

You can define up to 10 DNS configurations per instance. To view a list of configurations that are available for your instance, go to the Secrets engines > Public certificates page in the Secrets Manager UI.

You can define up to 10 DNS configurations per instance. To obtain a list of configurations that are available for your instance, you can use the List configurations API.

Before you begin

Before you get started, be sure that you have the required level of access. To manage engine configurations for your instance, you need the Manager service role or higher.

Supported DNS providers

You can connect the following DNS providers with your Secrets Manager service instance.

Table 1. Prerequisites - CIS
Prerequisites
Before you add a configuration for Cloud Internet Services (CIS), be sure that you: Create a CIS service instance. Create an authorization between Secrets Manager and CIS. If your CIS instance is located in another account, obtain the CRN of the instance and create an API key with the correct level of access.

Table 1. Prerequisites - Classic infrastructure
Prerequisites
Before you add a configuration for classic infrastructure, be sure that you: Obtain your classic infrastructure username. If you are using IBMid to log in to your account, your classic infrastructure username is your `<account_id>_<email_address>`. Create a classic infrastructure API key. Assign your user permissions to manage DNS in the account. For more information about managing classic infrastructure access, see Classic infrastructure permissions.

Table 1. Prerequisites - Manual DNS providers
Prerequisites
To use your own DNS provider, you must refer to your provider's documentation for instructions. No DNS provider configuration is required in Secrets Manager.

Adding a DNS provider configuration in the UI

You can add DNS provider configurations to your service instance by using the Secrets Manager UI.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets engines page, click the Public certificates tab.
In the DNS providers table, click Add.
Select the DNS provider that you want to use.

Currently, you can add configurations for Cloud Internet Services (CIS) and IBM Cloud classic infrastructure. You can also use your own DNS provider, but no configuration is required in this case.
Grant service access between Secrets Manager and your selected DNS provider.
1. If you choose CIS, grant access by selecting from a list of authorized CIS instances or by entering an API key.
  
  Don't have an authorization yet? You can create one in the IAM console. Optionally, you can grant access to CIS by providing an API key and the instance CRN. You can find the CRN in the Overview page of your CIS service instance. For more information about creating an API key for CIS, see Granting service access by using an API key
2. If you choose classic infrastructure, enter the username and API key that is associated with your account.
3. If you choose to use your own DNS provider, refer to your provider's documentation for instructions. No DNS provider configuration is required in Secrets Manager.
Click Add.

Adding a DNS provider configuration from the CLI

You can add DNS provider configurations to your service instance by using the Secrets Manager CLI. Manual DNS providers can be configured only by using the API.

To configure a secrets engine from the IBM Cloud CLI, run the ibmcloud secrets-manager configuration-create command.

ibmcloud secrets-manager configuration-create {
  "cloud_internet_services_apikey": "MY_APIKEY_WITH_MANAGER_ACCESS_TO_CIS",
  "cloud_internet_services_crn": "MY_CIS_CRN",
  "config_type": "public_cert_configuration_dns_cloud_internet_services",
  "name": "my-cloud-internet-services-config"}'

If you choose to use your own DNS provider, refer to your provider's documentation for instructions. No DNS provider configuration is required in Secrets Manager.

Adding a DNS provider configuration with the API

You can add DNS provider configurations to your service instance by using the Secrets Manager API.

If you choose to use your own DNS provider, refer to your provider's documentation for instructions. No DNS provider configuration is required in Secrets Manager.

Configuring Cloud Internet Services (CIS)

The following example shows a query that you can use to add a Cloud Internet Services (CIS) DNS configuration to your Secrets Manager instance. When you call the API, replace the cis_crn value with the CRN of the CIS instance that contains your domains.

If you need to access a CIS instance that is located in another account, provide a cis_apikey value that contains an API key with Manager service access on the Internet Services (internet-svs) service. For more information, see Granting service access to CIS.

curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
    "cloud_internet_services_apikey": "5ipu_ykv0PMp2MhxQnDMn7VzrkSlBwi3BOI8uthi_EXZ",
    "cloud_internet_services_crn": "crn:v1:bluemix:public:internet-svcs:global:a/128e84fcca45c1224aae525d31ef2b52:009a0357-1460-42b4-b903-10580aba7dd8::",
    "config_type": "public_cert_configuration_dns_cloud_internet_services",
    "name": "cloud-internet-services-config"
  }' \  
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

A successful response adds the configuration to your service instance. For more information about the required and optional request parameters, see Add a configuration.

Configuring classic infrastructure

The following example shows a query that you can use to add a classic infrastructure DNS configuration to your Secrets Manager instance. When you call the API, replace the classic_infrastructure_username and classic_infastructure_password (API key) values.

curl -X POST 
  --H 'Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
  "classic_infrastructure_password": "sRBm1jkHOH2kn9oBnK5R0ODsRBm1jkHOH2kn9oBnK5R0ODsRBm1jkHOH2kn9oBnK5R0OD",
  "classic_infrastructure_username": "1234567_JohnDoe@mail.com",
  "config_type": "public_cert_configuration_dns_classic_infrastructure",
  "name": "classic-infrastructure-config"
}' \  
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

A successful response adds the configuration to your service instance. For more information about the required and optional request parameters, see Add a configuration.

Adding a DNS provider configuration with Terraform

You can add DNS provider configurations to your service instance by using Terraform for Secrets Manager.

If you choose to use your own DNS provider, refer to your provider's documentation for instructions. No DNS provider configuration is required in Secrets Manager.

Configuring Cloud Internet Services (CIS) with Terraform

The following example shows a configuration that you can use to add a a Cloud Internet Services (CIS) DNS configuration to your Secrets Manager instance.

resource "ibm_sm_public_certificate_configuration_dns_cis" "my_dns_cis_config" {
   instance_id = local.instance_id
   region = local.region
   name = "my_DNS_CIS_config"
   cloud_internet_services_apikey = var.my_cis_apikey
   cloud_internet_services_crn = var.my_cis_crn
   }

Configuring classic infrastructure with Terraform

The following example shows a configuration that you can use to add a classic infrastructure DNS configuration to your Secrets Manager instance.

resource "ibm_sm_public_certificate_configuration_dns_classic_infrastructure" "my_dns_classic_config" {
   instance_id = local.instance_id
   region = local.region
   name = "my_DNS_config"
   classic_infrastructure_password = "username"
   classic_infrastructure_username = "password"
}

Deleting a DNS provider configuration in the UI

If you no longer need a configuration, you can delete it by using the Secrets Manager UI.

After you delete a configuration, the certificates that are associated with the DNS provider can no longer be rotated automatically. Do not delete configurations that are associated with certificates in your production apps or services.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets engines page, click the Public certificates tab.
Use the DNS providers section table to view the configurations in your instance.
In the row for the configuration that you want to delete, click the Actions menu > Delete.
Enter the name of the configuration to confirm its deletion.
Click Delete.

Deleting a DNS provider configuration with the API

You can delete configurations by calling the Secrets Manager API.

The following example shows a query that you can use to remove a DNS provider configuration from your instance. When you call the API, replace {config_name} with the name of the configuration that you want to delete.

curl -X DELETE 
--H "Authorization: Bearer {iam_token}" \
 "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{name}"

A successful response removes the configuration from your service instance. For more information about the required and optional request parameters, see Remove a configuration.

Retrieving a DNS provider configuration in the UI

You can retrieve a DNS provider's value by using the Secrets Manager UI.

In the Public certificates secret engine, click the Actions menu from the DNS providers table to open a list of options for your engine configuration.
To view the configuration value, click View configurationt.
Click Confirm after you ensure that you are in a safe environment.

The secret value is displayed for 15 seconds, then the dialog closes.

Retrieving a DNS provider configuration using CLI

You can retrieve a DNS provider's value by using the Secrets Manager CLI. In the following example command, replace the engine configuration name with your configuration's name.

ibmcloud secrets-manager configuration --name EXAMPLE_CONFIG --service-url https://{instance_ID}.{region}.secrets-manager.appdomain.cloud

Replace {instance_ID} and {region} with the values that apply to your Secrets Manager service instance. To find the endpoint URL that is specific to your instance, you can copy it from the Endpoints page in the Secrets Manager UI. For more information, see Viewing your endpoint URLs

Retrieving a DNS provider configuration using API

You can retrieve a DNS provider's value by using the Secrets Manager API. In the following example request, replace the engine configuration name with your configuration's name.

curl -X GET --location --header "Authorization: Bearer {iam_token}" \
--header "Accept: application/json" \
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{name}"

A successful response returns the value of the engine configuration, along with other metadata. For more information about the required and optional request parameters, see Get a secret.

Next steps

Order a certificate.