Install Linkerd using Cert-manager

Linkerd is a dedicated infrastructure layer that helps manage communication between services by automatically encrypting connections, handling retries, and timeouts. Installing the Linkerd add-on ensures load balancing for gRPC traffic as HUMMIX services scale. It also provides telemetry (success rates, latencies) and more..

Linkerd is essential for enabling scalable service support on the HUMMIX application side. Without it, scaling HUMMIX microservices will not function.

For instructions on preparing certificates using openssl for Linkerd and its installation, read the article Install Linkerd.

This article will cover how to:

  • Automate certificate preparation using the Cert-manager tool and install Linkerd;

Installing Linkerd involves four steps:

  1. Prepare certificates for Linkerd.
  2. Download the Helm chart and configuration file.
  3. Fill out the configuration file.
  4. Install the Linkerd chart using Helm in a Kubernetes cluster.

Step 1:  Prepare certificates for Linkerd

  1. Install Cert-manager and create namespaces. Cert-manager will use these to store resources related to the web interceptor:

kubectl create namespace linkerd
kubectl label namespace linkerd linkerd.io/is-control-plane=true config.linkerd.io/admission-webhooks=disabled linkerd.io/control-plane-ns=linkerd
kubectl annotate namespace linkerd linkerd.io/inject=disabled

  1. Install the step tool  to create a key pair for signing each certificate:

wget https://dl.smallstep.com/cli/docs-cli-install/latest/step-cli_amd64.deb
sudo dpkg -i step-cli_amd64.deb

  1. Generate certificates using step to use them for signing:
  • Web interceptor certificates;

Execute the command

 
#  Create CA keys
step certificate create webhook.linkerd.cluster.local caWebhook.crt caWebhook.key --profile root-ca --no-password --insecure --san webhook.linkerd.cluster.local --not-after=87600h
kubectl create secret tls webhook-issuer-tls --cert=caWebhook.crt --key=caWebhook.key --namespace=linkerd
# Create Issuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
 name: webhook-issuer
 namespace: linkerd
spec:
 ca:
   secretName: webhook-issuer-tls
EOF
# Create Certificate
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: linkerd-policy-validator
 namespace: linkerd
spec:
 secretName: linkerd-policy-validator-k8s-tls
 duration: 24h
 renewBefore: 1h
 issuerRef:
   name: webhook-issuer
   kind: Issuer
 commonName: linkerd-policy-validator.linkerd.svc
 dnsNames:
 - linkerd-policy-validator.linkerd.svc
 isCA: false
 privateKey:
   algorithm: ECDSA
   encoding: PKCS8
 usages:
 - server auth
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: linkerd-proxy-injector
 namespace: linkerd
spec:
 secretName: linkerd-proxy-injector-k8s-tls
 duration: 24h
 renewBefore: 1h
 issuerRef:
   name: webhook-issuer
   kind: Issuer
 commonName: linkerd-proxy-injector.linkerd.svc
 dnsNames:
 - linkerd-proxy-injector.linkerd.svc
 isCA: false
 privateKey:
   algorithm: ECDSA
 usages:
 - server auth
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: linkerd-sp-validator
 namespace: linkerd
spec:
 secretName: linkerd-sp-validator-k8s-tls
 duration: 24h
 renewBefore: 1h
 issuerRef:
   name: webhook-issuer
   kind: Issuer
 commonName: linkerd-sp-validator.linkerd.svc
 dnsNames:
 - linkerd-sp-validator.linkerd.svc
 isCA: false
 privateKey:
   algorithm: ECDSA
 usages:
 - server auth
EOF
 
  • Control Plane certificate.

Execute the command

 
# Create CA keys
step certificate create root.linkerd.cluster.local caRoot.crt caRoot.key --profile root-ca --no-password --insecure --not-after=87600h
kubectl create secret tls linkerd-trust-anchor --cert=caRoot.crt --key=caRoot.key --namespace=linkerd
# Create Issuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
 name: linkerd-trust-anchor
 namespace: linkerd
spec:
 ca:
   secretName: linkerd-trust-anchor
EOF
# Create Certificate
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
 name: linkerd-identity-issuer
 namespace: linkerd
spec:
 secretName: linkerd-identity-issuer
 duration: 48h
 renewBefore: 25h
 issuerRef:
   name: linkerd-trust-anchor
   kind: Issuer
 commonName: identity.linkerd.cluster.local
 dnsNames:
 - identity.linkerd.cluster.local
 isCA: true
 privateKey:
   algorithm: ECDSA
 usages:
 - cert sign
 - crl sign
 - server auth
 - client auth
EOF
 

Step 2: Download the Helm chart and configuration file

To install Linkerd via the internet, retrieve the configuration file values-linkerd.yaml by executing the following command:

helm repo add hummix https://charts.hummix.co
helm repo update
helm show values hummix/linkerd > values-linkerd.yaml

 

Obtaining the configuration file for installation in an offline environment:

  1. On a computer with internet access, download the latest version of the Linkerd chart archive from the HUMMIX repository using the command:

helm repo add hummix https://charts.hummix.co
helm repo update
helm pull hummix/linkerd

  1. Copy the downloaded linkerd-X.Y.Z.tgz chart archive to the server where it will be installed.
  2. Unpack the chart on the server and copy the default configuration file values.yaml to values-linkerd.yaml using the command:

tar -xf linkerd-X.Y.Z.tgz
cp linkerd/values.yaml values-linkerd.yaml

 

Step 3: Fill out the configuration file

Fill in the configuration file values-linkerd.yaml for installing Linkerd:

  1. Specify the DNS domain name of the Kubernetes cluster in the parameter linkerd.clusterDomain. In this example, the domain name is cluster.local:

# Linkerd settings
linkerd:
 # DNS name of the Kubernetes domain
 clusterDomain: cluster.local
 # adds PodSecurityPolicy resource (deprecated as of k8s v1.21)
 enablePSP: false
 # disable heartbeat
 disableHeartBeat: false  
...

  1. To ensure high availability, you may uncomment the parameters in the high availability settings section.

Example of enabling high availability

 
# linkerd settings
linkerd:
...
#
# parameters for high availability
 controllerReplicas: 3
 enablePodDisruptionBudget: true
 deploymentStrategy:
   rollingUpdate:
     maxUnavailable: 1
     maxSurge: 25%
 enablePodAntiAffinity: true
 proxy:
   resources:
     cpu:
       request: 100m
     memory:
       limit: 250Mi
       request: 20Mi
 controllerResources: &controller_resources
   cpu: &controller_resources_cpu
     limit: ""
     request: 100m
   memory:
     limit: 250Mi
     request: 50Mi
 destinationResources: *controller_resources
 identityResources:
   cpu: *controller_resources_cpu
   memory:
     limit: 250Mi
     request: 10Mi
 heartbeatResources: *controller_resources
 proxyInjectorResources: *controller_resources
 webhookFailurePolicy: Ignore
 spValidatorResources: *controller_resources
#
...

 
  1. If you have installed monitoring tools, specify the parameter for Linkerd metrics:

# Connection parameter for metrics collection
podMonitor:
  enabled: true

  1. If you install Linkerd in an isolated environment without internet access, fill out the connection parameters for the private registry.

How to fill out the connection parameters for the private registry

 

  1. Download the HUMMIX images and upload them to your local image registry. For more details, read Download HUMMIX images.
  2. Set the address and path in the parameters linkerd.controllerImage, linkerd.policyController.image.name, linkerd.proxy.image.name, linkerd.proxyInit.image.name.
  3. Specify the name of the secret with access rights to the private registry in the parameter linkerd.imagePullSecrets. The secret must be created manually and encrypted in Base64.

# linkerd settings
linkerd:
...
 # Parameters for connecting to a private registry
 # Address and path for the private registry
 controllerImage: registry.example.com/linkerd/controller
 policyController:
   image:
     # Address and path for the private registry
     name: registry.example.com/linkerd/policy-controller
 proxy:
   image:
     # Address and path for the private registry
     name: registry.example.com/linkerd/proxy
 proxyInit:
   image:
     # Address and path for the private registry
     name: registry.example.com/linkerd/proxy-init
 # he secret with access rights to the private registry must be manually created and encrypted in Base64
 imagePullSecrets:
   - name: myRegistryKeySecretName

Where the format is:

  • linkerd.controllerImage:
  • Address is registry.example.com.
  • Path is /linkerd/controller.
  • linkerd.policyController.image.name:
  • Address is registry.example.com.
  • Path is /linkerd/policy-controller.
  • linkerd.proxy.image.name:
  • Address is registry.example.com.
  • Path is /linkerd/proxy.
  • linkerd.proxyInit.image.name:
  • Address: registry.example.com.
  • Path is /linkerd/proxy-init.

Step 4: Install the Linkerd chart using Helm in a Kubernetes cluster

Install the Linkerd chart in namespace linkerd. The namespace will be created during installation if it has not been created earlier. Below is the installation command from the directory where the certificates were created in Step 1. If you are running the command from a different directory, specify the paths to the certificates created in Step 1 (caRoot.crt, caWebhook.crt).

For installation via the internet:

helm upgrade --install linkerd hummix/linkerd -f values-linkerd.yaml -n linkerd --create-namespace \
--set-file linkerd.identityTrustAnchorsPEM=caRoot.crt \
--set linkerd.identity.issuer.scheme=kubernetes.io/tls \
--set linkerd.policyValidator.externalSecret=true \
--set-file linkerd.policyValidator.caBundle=caWebhook.crt \
--set linkerd.proxyInjector.externalSecret=true \
--set-file linkerd.proxyInjector.caBundle=caWebhook.crt \
--set linkerd.profileValidator.externalSecret=true \
--set-file linkerd.profileValidator.caBundle=caWebhook.crt

For offline installation without internet access:

helm upgrade --install linkerd ./linkerd -f values-linkerd.yaml -n linkerd --create-namespace \
--set-file linkerd.identityTrustAnchorsPEM=caRoot.crt \
--set linkerd.identity.issuer.scheme=kubernetes.io/tls \
--set linkerd.policyValidator.externalSecret=true \
--set-file linkerd.policyValidator.caBundle=caWebhook.crt \
--set linkerd.proxyInjector.externalSecret=true \
--set-file linkerd.proxyInjector.caBundle=caWebhook.crt \
--set linkerd.profileValidator.externalSecret=true \
--set-file linkerd.profileValidator.caBundle=caWebhook.crt

Attention

After installing Linkerd, change the HUMMIX application settings and set up autoscaling of services. Read more in the Enable service autoscaling in HUMMIX On-Premises article.

Uninstall the Linkerd chart with Helm in a Kubernetes cluster

Attention

Before removing the Linkerd add-on component, disable autoscaling on the HUMMIX application side.

To delete the Linkerd chart in namespace linkerd, run the following command:

helm uninstall linkerd -n linkerd

 

install-linkerd.html install-hostpath-provisioner.html