diff --git a/linkerd.io/content/2.15/tasks/automatically-rotating-control-plane-tls-credentials.md b/linkerd.io/content/2.15/tasks/automatically-rotating-control-plane-tls-credentials.md index 3215b04470..5b0d105057 100644 --- a/linkerd.io/content/2.15/tasks/automatically-rotating-control-plane-tls-credentials.md +++ b/linkerd.io/content/2.15/tasks/automatically-rotating-control-plane-tls-credentials.md @@ -10,9 +10,10 @@ shared across clusters, and an *issuer certificate*, which is specific to the cluster. While Linkerd automatically rotates the per-proxy TLS certificates, it does not -rotate the issuer certificate. In this doc, we'll describe how to set up -automatic rotation of the issuer certificate and its corresponding private key -using the cert-manager project. +rotate the issuer certificate. Linkerd's out-of-the-box installations generate +static self-signed certificates with a validity of one year but require manual +rotation by the user to prevent expiry. While this setup is convenient for quick +start testing, it's not advisable nor recommended for production environments. {{< docs/production-note >}} @@ -23,17 +24,23 @@ for making TLS credentials from external sources available to Kubernetes clusters. Cert-manager is very flexible. You can configure it to pull certificates from -secrets managemenet solutions such as [Vault](https://www.vaultproject.io). In +secrets managemenet solutions such as [Vault](https://www.vaultproject.io). In this guide, we'll focus on a self-sufficient setup: we will configure cert-manager to act as an on-cluster [CA](https://en.wikipedia.org/wiki/Certificate_authority) and have it re-issue Linkerd's issuer certificate and private key on a periodic basis, derived from -the trust anchor. +the trust anchor. Additionally, we will use trust-manager create a trust bundle +which will allow Linkerd to verify the authenticity of certificates issued by +cert-manager. ### Cert manager as an on-cluster CA -As a first step, [install cert-manager on your -cluster](https://cert-manager.io/docs/installation/). +As a first step, +[install cert-manager on your cluster](https://cert-manager.io/docs/installation/), +then +[install trust-manager](https://cert-manager.io/docs/trust/trust-manager/installation/) +and configure it to use "linkerd" as the +[trust namespace](https://cert-manager.io/docs/trust/trust-manager/installation/#trust-namespace). Next, create the namespace that cert-manager will use to store its Linkerd-related resources. For simplicity, we suggest reusing the default @@ -43,46 +50,111 @@ Linkerd control plane namespace: kubectl create namespace linkerd ``` -#### Save the signing key pair as a Secret +#### Give cert-manager necessary RBAC permissions -Next, using the [`step`](https://smallstep.com/cli/) tool, create a signing key -pair and store it in a Kubernetes Secret in the namespace created above: +By default cert-manager will only create certificate secrets in the namespace +where it is installed. Linkerd, however, requires the cert secrets to be created +in the linkerd namespace. To do this we will create a `ServiceAccount` for +cert-manager in the linkerd namespace with the required permissions. ```bash -step certificate create root.linkerd.cluster.local ca.crt ca.key \ - --profile root-ca --no-password --insecure && - kubectl create secret tls \ - linkerd-trust-anchor \ - --cert=ca.crt \ - --key=ca.key \ - --namespace=linkerd +kubectl apply -f - <}} ## Install Cert manager -As a first step, [install cert-manager on your -cluster](https://cert-manager.io/docs/installation/) -and create the namespaces that cert-manager will use to store its +As a first step, +[install cert-manager on your cluster](https://cert-manager.io/docs/installation/) +and create the namespaces that cert-manager will use to store its webhook-related resources. For simplicity, we suggest using the default namespace linkerd uses: @@ -51,66 +52,116 @@ kubectl create namespace linkerd-jaeger kubectl label namespace linkerd-jaeger linkerd.io/extension=jaeger ``` -## Save the signing key pair as a Secret +{{< note >}} The following namespace-bound templates and commands can be re-used +for Linkerd extensions including viz and jaeger by modifying the namespace of +each to match that of the extension. {{< /note >}} -Next, we will use the [`step`](https://smallstep.com/cli/) tool, to create a -signing key pair which will be used to sign each of the webhook certificates: +## Give cert-manager necessary RBAC permissions + +By default cert-manager will only create certificate secrets in the namespace +where it is installed. Linkerd and its extensions, however, require the cert +secrets to be created in the namespaces where they run. To do this we will +create a `ServiceAccount` for cert-manager in the appropriate namespaces with +the required permissions. ```bash -step certificate create webhook.linkerd.cluster.local ca.crt ca.key \ - --profile root-ca --no-password --insecure --san webhook.linkerd.cluster.local +kubectl apply -f - <}} -When installing the `linkerd-control-plane` chart, you _must_ provide the -issuer trust root and issuer credentials as described in [Installing Linkerd -with Helm](../install-helm/). -{{< /note >}} +{{< note >}} When installing the `linkerd-control-plane` chart, you _must_ +provide the issuer trust root and issuer credentials as described in +[Installing Linkerd with Helm](../install-helm/). {{< /note >}} -See [Automatically Rotating Control Plane TLS -Credentials](../automatically-rotating-control-plane-tls-credentials/) +See +[Automatically Rotating Control Plane TLS Credentials](../automatically-rotating-control-plane-tls-credentials/) for details on how to do something similar for control plane credentials.