--- name: containers-secrets title: Managing TLS and non-TLS certificates and secrets description: Learn how you can use certificates and secrets in your cluster. last-updated: 2026-08-06 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/containers?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. # Managing TLS and non-TLS certificates and secrets {: #secrets} Learn how you can use certificates and secrets in your cluster. {: shortdesc} Consider using [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) to centrally manage and automatically update your secrets. {: tip} ## Managing TLS certificates and secrets with Ingress {: #tls} Your Ingress TLS certificate is stored as a Kubernetes secret. To manage the TLS secrets in your cluster, you can use the `ibmcloud ks ingress secret` set of commands. {: shortdesc} For example, you can import a certificate from Secrets Manager to a Kubernetes secret in your cluster by running the following command. ```sh ibmcloud ks ingress secret create --cluster CLUSTER_NAME_OR_ID --cert-crn CRN --name SECRET_NAME --namespace default ``` {: pre} To import the certificate with the `ibmcloud ks ingress secret create` command, you must have a default [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) instance registered to your cluster. If you do not have a Secrets Manager instance and your secrets are instead written directly to your cluster, your secrets do not have the required CRN value and you must manually copy them with `kubectl` commands. {: important} To view all Ingress secrets for TLS certificates in your cluster, run the following command. ```sh ibmcloud ks ingress secret ls -c CLUSTER ``` {: pre} ### Setting up TLS secrets for the IBM-provided Ingress subdomain {: #tls-default} IBM provides an Ingress subdomain and a default TLS certificate, stored as a Kubernetes secret in your cluster, that you can specify in your Ingress resource. IBM-provided TLS certificates are signed by LetsEncrypt and are fully managed by IBM. {: shortdesc} The IBM-provided Ingress subdomain wildcard, `*.--0000..containers.appdomain.cloud`, is registered by default for your cluster. The IBM-provided TLS certificate is a wildcard certificate and can be used for the wildcard subdomain. {: tip} Follow the steps to use the default TLS certificate for the IBM-provided Ingress subdomain. 1. Get the name of the secret where your default TLS certificate is stored. Note that this is the secret name you specify in the `spec.tls` section of your Ingress resource. ```sh ibmcloud ks cluster get -c CLUSTER | grep Ingress ``` {: pre} Example output ```sh Ingress Subdomain: mycluster--0000.us-south.containers.appdomain.cloud Ingress Secret: mycluster--0000 ``` {: screen} 2. View the secret details and note the CRN value. This is the CRN of the TLS certificate. If you do not have a default [Secrets Manager] instance registered to your cluster, your secret does not have a CRN. See the note in the following step for more details. ```sh ibmcloud ks ingress secret get -c CLUSTER --name SECRET_NAME --namespace default ``` {: pre} 3. Create a secret for the default TLS certificate in each namespace where your Ingress resources or apps exist. Specify the TLS certificate CRN with the `--cert-crn` command option. Alternatively, you can set the secret as the `defaultCertificate` in the [`ibm-ingress-deploy-config` ConfigMap](https://cloud.ibm.com/docs/containers?topic=containers-comm-ingress-annotations&format=markdown#comm-customize-deploy). {: tip} ```sh ibmcloud ks ingress secret create --cluster CLUSTER_NAME_OR_ID --cert-crn CRN --name SECRET_NAME --namespace default ``` {: pre} To copy the secret with the **`ibmcloud ks ingress secret create`** command, you must have a default [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) instance registered to your cluster. If you do not have a Secrets Manager instance and your secrets are instead written directly to your cluster, your secrets do not have the required CRN value and you must manually copy them with `kubectl` commands. {: important} ### Setting up TLS secrets for custom subdomains {: #tls-custom} If you define a custom subdomain in your Ingress resource, you can use your own TLS certificate to manage TLS termination. You must create a Kubernetes secret to store the TLS certificate, then import this secret into each namespace where your apps exist. {: shortdesc} By storing custom TLS certificates in [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown), you can import your certificates directly into a Kubernetes secret in your cluster. {: tip} 1. Create or import a secret for the TLS certificate in the namespace where your Ingress resource exists. For example, you can import a secret from Secrets Manager into your cluster by running the following command. Specify the TLS certificate's CRN with the `--cert-crn` command option. To import the certificate with the `ibmcloud ks ingress secret create` command, you must have a default [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) instance registered to your cluster. If you do not have a Secrets Manager instance and your secrets are instead written directly to your cluster, your secrets do not have the required CRN value and you must manually copy them with `kubectl` commands. {: important} ```sh ibmcloud ks ingress secret create --name SECRET_NAME --cluster CLUSTER_NAME_OR_ID --cert-crn CERTIFICATE_CRN --namespace default ``` {: pre} 2. Repeat the previous step for each namespace where your apps exist. ## Managing non-TLS secrets {: #non-tls} To manage non-TLS secrets, you can use the `ibmcloud ks ingress secret` commands. {: shortdesc} There are 5 types of non-TLS secrets: - **Arbitrary secrets** hold one string value. - **IAM credentials** hold an IAM API key. - **Username and password secrets** hold a username and password as two separate values. - **Key values** hold JSON values. - **Custom credentials** holds custom (string) values. Learn how you can centrally manage your non-TLS secrets with [IBM Cloud Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown). With Secrets Manager, you can create managed Kubernetes secrets, update your secrets automatically, create secret groups that control who has access to the secrets in your cluster, and more. {: tip} ### Creating a non-TLS secret in your cluster {: #non-tls-create} Create a non-TLS secret by specifying the `--type Opaque` option in the **`ibmcloud ks ingress secret create`** command. With the `Opaque` type, you can include multiple non-certificate CRN values. If the `--type` option is not specified, TLS is applied by default. For more information and additional command options, see the [CLI reference](https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli&format=markdown#ingress-secret-create-cli). {: shortdesc} The following example command creates a non-TLS secret with the `Opaque` type specified. Non-TLS secrets require at least one secret [field](#non-tls-field-add). Note that how you specify the `--field` option varies [based on the type of secret you create](#non-tls-field-add). ```sh ibmcloud ks ingress secret create -c cluster-test --name example-secret --namespace default --field crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa1a11111aaa1a1111aa1aa111:111a1111-11a1 --type Opaque ``` {: pre} To verify that the secret is created, list all secrets in the namespace. ```sh kubectl get secret -n default ``` {: pre} The following example shows the output. ```sh NAME TYPE DATA AGE all-icr-io kubernetes.io/dockerconfigjson 1 41h default-token-8t6xw kubernetes.io/service-account-token 3 41h example-secret Opaque 3m ``` {: screen} ### Managing non-TLS secret fields {: #non-tls-field} A secret field is a key-value pair that is stored in a non-TLS secret. Refer to the following examples to view, add, update, or remove non-TLS secret fields. {: shortdesc} #### Viewing field values {: #non-tls-field-view} You can view the values of a secret's fields by getting the details of the secret. {: shortdesc} ```sh kubectl get secret -n default example-secret -o yaml ``` {: pre} The following example output shows the secret fields and their values in the `data` section. ```yaml apiVersion: v1 data: arbitraryFVT: AAAaaAAaAAA1AAAaaAAa userCredsFVT_password: aAAaa1aaaA= userCredsFVT_username: aAAaaa== kind: Secret metadata: annotations: ingress.cloud.ibm.com/cert-source: ibm razee.io/build-url: https://url.com razee.io/source-url: https://url.com creationTimestamp: "2022-11-08T19:45:05Z" name: example-secret namespace: default resourceVersion: "111111" uid: 1aaa1111-1a11-111a-a1a1-11111a1a1a1a type: Opaque ``` {: screen} You can also list the fields in a secret with the `ibmcloud ks ingress secret field ls` and `ibmcloud ks ingress secret get` commands, but the outputs include only the field name and not the value associated with it. #### Adding a secret field {: #non-tls-field-add} Add a secret field to a non-TLS secret by running the [`ibmcloud ks ingress secret field add`](https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli&format=markdown#ingress-secret-field-add-cli) command with the `--field` option. You can also use this option to add fields when you create a secret with the [**`ibmcloud ks ingress secret create`**](https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli&format=markdown#ingress-secret-create-cli) command. This option is not supported for TLS secrets. {: shortdesc} There are three ways to specify the `--field` option. The one you choose depends on the secret type and how you want to name the field in the secret. | Option | Format | Description | Supported secret types | | ------ | ------ | ----------- | ---------------------- | | Default | `--field ` | The name of the added field is the [default field name](#default-field-name) for the secret type of the given CRN. | All non-TLS secret types | | Named | `--field =` | Use this option to specify a name for the added field. The name of the added field is the value specified for ``. | - Arbitrary \n - IAM credentials | | Prefixed | `--field prefix=` | The name of the added field is the [default field name](#default-field-name) for the secret type specified by the given CRN, prefixed by the name of the secret specified by the `` and an underscore. | - IAM credentials \n - username/password \n - key/value \n - Custom credentials | {: caption="Options for adding fields to non-TLS secrets"} The default field names are `arbitrary` for arbitrary secrets, `api_key` for IAM credentials, `username` or `password` for user credentials, and `key` for key-value.{: #default-field-name} The following example adds three secret fields - using the same IAM credentials secret, named `iam` - to demonstrate how the different `--field` options affect the resulting field name. You can [view the fields](#non-tls-field-view) added to a secret by running `kubectl get secret` and viewing the `data` block of the output. ```sh ibmcloud ks ingress secret field add --cluster example-cluster --name example-iam-secret --namespace default --field crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa-1a11-111a-aa1a-1111aa1aa111:secret:111a1111-11a1-11aa-a1a1-111aa12345aa --field custom_iam_name=crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa-1a11-111a-aa1a-1111aa1aa111:secret:111a1111-11a1-11aa-a1a1-111aa12345aa --field prefix=crn:v1:bluemix:public:secrets-manager:us-south:a/1aa111aa-1a11-111a-aa1a-1111aa1aa111:secret:111a1111-11a1-11aa-a1a1-111aa12345aa ``` {: pre} Example fields listed in the `data` block of the secret details. ```sh data: api_key: bmZrUHR1VS1fNVpMOExsTmIxeTdQcXFTSENMc2pTUjRsNTQyTzZkZ2ZQMkk= # Default field type using the default `api_key` field name custom_iam_name: bmZrUHR1VS1fNVpMOExsTmIxeTdQcXFTSENMc2pTUjRsNTQyTzZkZ2ZQMkk= # Named field type using the specified `custom_iam_name` field name. iam_api_key: bmZrUHR1VS1fNVpMOExsTmIxeTdQcXFTSENMc2pTUjRsNTQyTzZkZ2ZQMkk= # Prefixed field type using the `iam` name in Secrets Manager followed by the `api_key` default name. ``` {: screen} #### Updating secret fields {: #non-tls-field-update} Run the **`ingress secret update`** command to update a secret field's values. Note that this does not update the CRN. For more information and command options, see the [CLI reference](https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli&format=markdown#ingress-secret-update-cli). {: #shortdesc} ```sh ibmcloud ks ingress secret update --cluster example-cluster --name example-secret --namespace default ``` {: pre} #### Removing a secret field {: #non-tls-field-rm} You can remove a secret field from a non-TLS secret. For more information and command options, see the [CLI reference](https://cloud.ibm.com/docs/containers?topic=containers-kubernetes-service-cli&format=markdown#ingress-secret-field-add-cli). {: shortdesc} ```sh ibmcloud ks ingress secret field rm -c example-cluster --name example-secret --namespace default --field-name example-Field ``` {: pre} You can verify that the field is removed by checking the `data` block of the secret's details. ```sh kubectl get secret -n default example-secret -o yaml ``` {: pre} ## Secrets FAQ {: #secrets-faq} Review the answers to commonly asked questions about managing secrets in your cluster. {: shortdesc} Are my secrets automatically updated if I do not create and register a [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) instance? : If you do not register a Secrets Manager instance 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 ks 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 did not create and register a [Secrets Manager](https://cloud.ibm.com/docs/containers?topic=containers-secrets-mgr&format=markdown) instance. How do I manage my secrets? : If you don't register a Secrets Manager instance, IBM Cloud Kubernetes Service automatically updates only the default Ingress secret. You are responsible for managing any other secrets by using **`kubectl`** commands or another rotation method. If your secrets reference the default Ingress certificate, remove them by using **`ibmcloud ks ingress secret rm`**.