--- name: openshift-secrets-mgr title: Setting up Secrets Manager in your Red Hat OpenShift cluster description: When you integrate IBM Cloud Secrets Manager with your Red Hat OpenShift on IBM Cloud cluster, you can centrally manage Ingress subdomain certificates and other secrets. last-updated: 2026-08-06 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/openshift?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Setting up Secrets Manager in your Red Hat OpenShift cluster {: #secrets-mgr} When you integrate IBM Cloud Secrets Manager with your Red Hat OpenShift on IBM Cloud cluster, you can centrally manage Ingress subdomain certificates and other secrets. {: shortdesc} ## About Secrets Manager {: #secrets-mgr_about} With Secrets Manager, you can use a single service to manage your secrets and control who has access to them. A Secrets Manager instance is not automatically provisioned in your cluster. However, you can use a single Secrets Manager instance across multiple clusters, and a single cluster can have more than one instance. ### What functionality can I gain with Secrets Manager? {: #secrets-mgr_about_functionality} With Secrets Manager, you can: - Create managed Kubernetes secrets with Ingress TLS certificates included. - Create Kubernetes secrets of any type by using the CRN of any Secrets Manager instance you own. - Automatically update your secrets in your cluster on a regular basis. - Track the expiration dates of your certificates from the IBM Cloud console. - Control who has access to your secrets by creating secret groups for approved users. Note that to have your secrets automatically updated, you must register at least one Secrets Manager instance to your cluster. For more information, see [Registering your Secrets Manager instance to your cluster](#secrets-mgr_setup_register). {: note} ## Secrets Manager FAQ {: #secrets-mgr_migration_faq} Keep the following points in mind when using Secrets Manager. {: shortdesc} What types of secrets are supported with Secrets Manager? : Secrets Manager supports IAM credentials, key-value secrets, user credentials, arbitrary secrets, and Kubernetes secrets. For Kubernetes secrets, Secrets Manager supports both TLS and non-TLS (Opaque) secret types. With TLS secrets, you can specify one certificate CRN. With non-TLS secrets, you can specify multiple fields to pull non-certificate secrets. If you do not specify a secret type when you create a secret, TLS is applied by default. For more information on supported secrets, see [Working with secrets of different types](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-what-is-secret&format=markdown#secret-types). Are secrets that are stored in a registered Secrets Manager instance automatically updated? : Yes. If you have a Secrets Manager instance registered to your cluster, the secrets on the cluster are automatically updated with the values from Secrets Manager once a day. These updates are made using the value of the secret from the corresponding CRN. Are my secrets automatically updated if I do not create and register a Secrets Manager instance? : If you do not have a Secrets Manager instance registered to your cluster, your default Ingress secrets continue to update automatically every 90 days and are applied to your cluster. However, any secrets you created that *reference* the default Ingress secret are not automatically updated. : **Example scenario**: You have a default Ingress certificate in the `default` namespace. You run the **`ibmcloud oc ingress secret create`** command and reference the CRN of the default Ingress certificate to mirror the certificate in the `istio-system` namespace. Without a Secrets Manager instance, the default Ingress certificate in the `default` namespace automatically updates. However, you are responsible for regularly updating the certificate in the `istio-system` namespace with the **`kubectl`** commands or another rotation method. I created secrets that reference the default Ingress certificate, but I have not created and registered a Secrets Manager instance. How do I manage my secrets? : If you don't register a Secrets Manager instance, Red Hat OpenShift on IBM Cloud only automatically updates the default Ingress secret. You are responsible for managing any other secrets by using **`kubectl`** commands or another rotation method. If you have any secrets that reference the default Ingress certificate, you should remove them by using **`ibmcloud ks ingress secret rm`**. What is the difference between the `ibmcloud oc ingress instance` CLI commands and the `ibmcloud oc ingress secret` CLI commands? : There are two sets of CLI commands that work directly with Secrets Manager instances in Red Hat OpenShift on IBM Cloud: the `ibmcloud oc ingress secret` commands and the `ibmcloud oc ingress instance` commands. The `ibmcloud oc ingress instance` commands are used to manage your Secrets Manager instances. The `ibmcloud oc ingress secret` commands are used to manage your Ingress secrets that are stored in a Secrets Manager instance or secrets that are written directly to the cluster. ## Setting up your Secrets Manager instance {: #secrets-mgr_setup} Follow the steps to set up Secrets Manager in your cluster. {: shortdesc} ### Enable service-to-service communication {: #secrets-mgr_setup_s2s} {: step} Integrating Secrets Manager with your Red Hat OpenShift on IBM Cloud cluster requires service-to-service communication authorization. Follow the steps to set up the authorization. For additional info, see [Integrations for Secrets Manager](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-integrations&format=markdown#create-authorization). {: shortdesc} 1. In the IBM Cloud console, click **Manage** > **Access (IAM)**. 2. Click **Authorizations**. 3. Click **Create**. 4. In the **Source service** list, select **Kubernetes Service**. 5. Select the option to scope the access to **All resources**. 6. In the **Target service** list, select **Secrets Manager**. 7. Select the option to scope the access to **All resources**. 8. In the **Service access** section, check the **Manager** option. 9. Click **Authorize**. ### Create a Secrets Manager instance {: #secrets-mgr_setup_create} {: step} To create a Secrets Manager instance in the CLI or the UI, refer to the Secrets Manager documentation. It might take several minutes for your Secrets Manager instance to fully provision. {: shortdesc} - [Create a Secrets Manager instance in CLI](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&interface=cli&format=markdown). - [Create a Secrets Manager instance in the UI](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-create-instance&format=markdown). When you create a Secrets Manager instance, it is not provisioned directly in your cluster. You must register your new Secrets Manager instance with your cluster in the next step. {: note} ### Register your Secrets Manager instance to your cluster {: #secrets-mgr_setup_register} {: step} Follow the steps to register your Secrets Manager instance to your cluster. {: shortdesc} 1. Get the CRN of the Secrets Manager instance. In the output, the CRN is in the **ID** row. ```sh ibmcloud resource service-instance ``` {: pre} Example output ```sh Name: my-secrets-manager-instance ID: crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1-111a-1111-1a1a1a1111a1: GUID: 111a1111-11a1-111a-1111-1a1a1a1111a1 Location: us-south Service Name: secrets-manager Service Plan Name: standard Resource Group Name: default State: active Type: service_instance Sub Type: Created at: 2022-06-08T12:46:45Z Created by: user@ibm.com Updated at: 2022-06-08T12:54:45Z ``` {: screen} 2. Register the instance to your cluster. Specify the instance CRN found in the previous step. If you want to register an instance to a cluster and also [set it as the default instance](#secrets-mgr_setup_default), include the `--is-default` option. Otherwise, you can set a default instance with the `ibmcloud oc ingress instance default set` command. {: tip} ```sh ibmcloud oc ingress instance register --cluster CLUSTER_NAME_OR_ID --crn INSTANCE_CRN [--is-default] ``` {: pre} 3. Verify that the Secrets Manager instance was registered to the cluster. ```sh ibmcloud oc ingress instance ls --cluster CLUSTER_NAME_OR_ID ``` {: pre} Example output ```sh Name Type Is Default Status Secret Group CRN my-secrets-manager-instance secrets-manager false created default crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1-111a-1111-1a1a1a1111a1:: ``` {: pre} You can specify a Secrets Manager instance and a secret group when you [create a cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-clusters&format=markdown) with the [`ibmcloud oc cluster create classic`](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-create-classic-cli) or [`ibmcloud oc cluster create vpc-gen2`](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-create-vpc-gen2-cli) commands. Use the `--sm-instance` option to register an instance to the cluster and the `--sm-group` option to specify a secret group that can access the secrets on the cluster. See [Registering a Secrets Manager instance when creating a cluster](#secrets-mgr_cluster_create). {: tip} ### Set a default Secrets Manager instance and regenerate your secrets {: #secrets-mgr_setup_default} {: step} When you set a default Secrets Manager instance, all new Ingress subdomain certificates are stored in that instance. {: shortdesc} 1. Run the command to set the new default instance. You can optionally specify a [secret group](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-groups&format=markdown) that is allowed access to the secrets in the instance. ```sh ibmcloud oc ingress instance default set --cluster CLUSTER_NAME_OR_ID --name INSTANCE_NAME --secret-group SECRET_GROUP_ID ``` {: pre} 2. Regenerate your secrets. Any secrets that are managed by IBM, such as your default Ingress secrets, are uploaded to the new default instance. These secrets are automatically updated and the CRN is changed to reference the Secrets Manager instance. 1. List the nlb-dns subdomains in your cluster. ```sh ibmcloud oc nlb-dns ls --cluster CLUSTER_NAME_OR_ID ``` {: pre} 2. For each subdomain in your cluster, run the command to regenerate your IBM-managed secrets. This updates the CRN of these secrets to reference the CRN of the new default Secrets Manager instance. Regenerating your secrets is rate-limited to five times per week. Follow the steps in this document carefully, as repeating them might cause you to reach the limit. If you do not regenerate your secrets, or if you have reached the limit, your secrets are uploaded to your Secrets Manager instance at the next renewal cycle. {: important} ```sh ibmcloud oc nlb-dns secret regenerate --cluster CLUSTER_NAME_OR_ID --nlb-subdomain NLB_SUBDOMAIN ``` {: pre} 3. Verify that your default Ingress secrets regenerated. In the output, the CRN of the default Ingress secrets should contain `secrets-manager`. It might take several minutes for your secrets to regenerate. During this process, the **Status** column in the output says `regenerating` and switches to `created` when the regeneration is complete. {: note} ```sh ibmcloud oc ingress secret ls --show-crn --cluster CLUSTER_NAME_OR_ID ``` {: pre} Example output ```sh Name Namespace Expiry Domains Status Type CRN secret-11111aa1a1a11aa1111111-000 default 3 months from now secret-11111aa1a1a.us-s…domain.cloud created TLS crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1:secret:a111aa11-11a1 secret-22222aa2a2a22aa2222222-000 default 3 months from now secret-22222aa2a2a.us-s…domain.cloud created TLS crn:v1:bluemix:public:secrets-manager:us-south:a/2aa222aa2:secret:a222aa22-22a2 ``` {: screen} ## Controlling access to your secrets with secret groups {: #secrets-mgr_groups} With Secrets Manager, you can use secret groups to control who has access to the secrets in your cluster. A secret group can be assigned to an IAM access group so that only select users or service IDs can access the secrets within the secret group. For more information, see [Organizing your secrets](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-secret-groups&interface=ui&format=markdown). {: shortdesc} ## Registering a Secrets Manager instance when creating a cluster {: #secrets-mgr_cluster_create} If you are [creating a new Classic or VPC cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-clusters&format=markdown), you can register an existing Secrets Manager instance and secret group to the cluster during creation. Secrets in the cluster are stored in the Secrets Manager instance and applied to the secret group. {: shortdesc} The Secrets Manager instance registered during cluster create does not automatically become the default Secrets Manager instance. You must still [set the default instance](#secrets-mgr_setup_default) manually. {: note} If you [create a cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-clusters&format=markdown) in the CLI with the [`ibmcloud oc cluster create classic`](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-create-classic-cli) or [`ibmcloud oc cluster create vpc-gen2`](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-create-vpc-gen2-cli), you can specify a Secrets Manager instance or secret group with the following command options: - `--sm-instance`: Use this option to register a Secrets Manager instance to the cluster by specifying the instance CRN. To find the CRN of a Secrets Manager instance, run `ibmcloud resource service-instance ` or navigate to your resource list in the UI and click the instance. - `--sm-group`: Use this option to specify the ID of the secret group. To find the secret group ID, run `ibmcloud secrets-manager secret-groups`. If you create a cluster in the UI, follow these steps to specify a Secrets Manager instance or secret group: 1. In the **Integrations** section of the cluster create page, select the option to enable **Secrets Manager**. 2. From the **Secrets Manager instance** drop down menu, select the instance you want to register to the cluster. If no instances are available, [create one](#secrets-mgr_setup_create). 3. From the **Secrets Manager group** drop down menu, select the secret group you want to apply. 4. Create the cluster. 5. Check that the Secrets Manager instance is registered to the cluster. 1. When your cluster is fully provisioned, click the cluster to view the cluster details. Under **Integrations**, find the **Secrets Manager** heading and click **Manage**. 2. In the side panel, check that correct instance is listed under **Registered Secrets Manager instances**. 3. To register additional instances to the cluster, click **Register instances**.