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 theibm-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 withkubectl
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 withkubectl
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.
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> . |
|
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. |
|
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 theibmcloud ks ingress secret create
command and reference the CRN of the default Ingress certificate to mirror the certificate in theistio-system
namespace. Without a Secrets Manager instance, the default Ingress certificate in thedefault
namespace automatically updates. However, you are responsible for regularly updating the certificate in theistio-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 usingibmcloud ks ingress secret rm
.