Managing TLS and non-TLS certificates and secrets

Learn how you can use certificates and secrets in your cluster.

Consider using Secrets Manager to centrally manage and automatically update your secrets.

Managing TLS certificates and secrets with Ingress

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.

For example, you can import a certificate from Secrets Manager to a Kubernetes secret in your cluster by running the following command.

ibmcloud ks ingress secret create --cluster <cluster_name_or_ID> --cert-crn <crn> --name <secret_name> --namespace default

To import the certificate with the ibmcloud ks ingress secret create command, you must have a default Secrets Manager 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.

To view all Ingress secrets for TLS certificates in your cluster, run the following command.

ibmcloud ks ingress secret ls -c <cluster>

Setting up TLS secrets for the IBM-provided Ingress subdomain

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.

The IBM-provided Ingress subdomain wildcard, *.<cluster_name>.<globally_unique_account_HASH>-0000.<region>.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.

Follow the steps to use the default TLS certificate for the IBM-provided Ingress subdomain.

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.

ibmcloud ks cluster get -c <cluster> | grep Ingress

Example output

Ingress Subdomain:      mycluster-<hash>-0000.us-south.containers.appdomain.cloud
Ingress Secret:         mycluster-<hash>-0000

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.
```
ibmcloud ks ingress secret get -c <cluster> --name <secret_name> --namespace default
```
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.
```
ibmcloud ks ingress secret create --cluster <cluster_name_or_ID> --cert-crn <CRN> --name <secret_name> --namespace default
```
To copy the secret with the ibmcloud ks ingress secret create command, you must have a default Secrets Manager 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.

Setting up TLS secrets for custom subdomains

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.

By storing custom TLS certificates in Secrets Manager, you can import your certificates directly into a Kubernetes secret in your cluster.

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 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.
```
ibmcloud ks ingress secret create --name <secret_name> --cluster <cluster_name_or_ID> --cert-crn <certificate_crn> --namespace default
```
Repeat the previous step for each namespace where your apps exist.

Managing non-TLS secrets

To manage non-TLS secrets, you can use the ibmcloud ks ingress secret commands.

There are 4 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.

Learn how you can centrally manage your non-TLS secrets with IBM Cloud Secrets Manager. 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.

Creating a non-TLS secret in your cluster

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.

The following example command creates a non-TLS secret with the Opaque type specified. Non-TLS secrets require at least one secret field. Note that how you specify the --field option varies based on the type of secret you create.

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

To verify that the secret is created, list all secrets in the namespace.

kubectl get secret -n default

The following example shows the output.

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

Managing non-TLS secret fields

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.

Viewing field values

You can view the values of a secret's fields by getting the details of the secret.

kubectl get secret -n default example-secret -o yaml

The following example output shows the secret fields and their values in the data section.

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://travis.ibm.com/alchemy-containers/armada-ingress-secret-mgr/builds/78876583
    razee.io/source-url: https://github.ibm.com/alchemy-containers/armada-ingress-secret-mgr/commit/651fa822632128163cf638c47f0a14b1e0e2915a
  creationTimestamp: "2022-11-08T19:45:05Z"
  name: example-secret
  namespace: default
  resourceVersion: "111111"
  uid: 1aaa1111-1a11-111a-a1a1-11111a1a1a1a
type: Opaque

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

Add a secret field to a non-TLS secret by running the ibmcloud ks ingress secret field add 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 command. This option is not supported for TLS secrets.

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.

Options for adding fields to non-TLS secrets
Option	Format	Description	Supported secret types
Default	`--field <crn>`	The name of the added field is the default field name for the secret type of the given CRN.	All non-TLS secret types
Named	`--field <name>=<crn>`	Use this option to specify a name for the added field. The name of the added field is the value specified for `<name>`.	Arbitrary IAM credentials
Prefixed	`--field prefix=<crn>`	The name of the added field is the default field name for the secret type specified by the given CRN, prefixed by the name of the secret specified by the `<crn>` and an underscore.	IAM credentials username/password key/value

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.

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 added to a secret by running kubectl get secret and viewing the data block of the output.

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

Example fields listed in the data block of the secret details.

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.

Updating secret fields

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.

ibmcloud ks ingress secret update --cluster example-cluster --name example-secret --namespace default

Removing a secret field

You can remove a secret field from a non-TLS secret. For more information and command options, see the CLI reference.

ibmcloud ks ingress secret field rm -c example-cluster --name example-secret --namespace default --field-name example-Field

You can verify that the field is removed by checking the data block of the secret's details.

kubectl get secret -n default example-secret -o yaml

Secrets FAQ

Review the answers to commonly asked questions about managing secrets in your cluster.

Are my secrets automatically updated if I do not create and register a Secrets Manager 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 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.