SPK Cert Manager¶

Overview¶

The Service Proxy for Kubernetes (SPK) Pods communicate over secure channels using the gRPC (remote procedure call) framework. To establish secure gRPC communication, SSL/TLS keys and certificates must be generated in the cluster. As an added layer of security, and to avoid service disruptions that may occur due to expired SSL/TLS certificates, a rotation schedule should be implemented, regenerating SSL/TLS certificates at specified intervals. The SPK Certificate Manager integrates with a cluster Certificate Authority (CA), to provide the SPK Pods with CA signed certificates at a regularly scheduled interval.

This document guides you through installing the SPK Cert Manager, and generating the required SSL/TLS certificates and keys.

_images/spk_info.png Note: The gRPC channel is established over TCP service port 8750.

CA signing certificate¶

To sign SPK Pod certificates, a self-signed certificate authority (CA) signing certificate and key (keypair) can be generated when installing the SPK Cert Manager. The CA signing keypair is installed in the cluster as a Secret, and will be referenced by a Kubernetes ClusterIssuer object. You can also provide a custom CA and specify the secret name in values yaml file. When the Cert Manager generates certificate signing requests (CSRs) for the SPK Pods, it will use this CA to sign and return new Pod Certificates across all cluster namespaces.

Pod certificates¶

All communication endpoints will generate Certificate Signing Request (CSR) and receive a Certificate object when the Pod is installed. The Cert Manager will rotate, or generate new CSRs, based on the duration parameter set in the Pod’s Certificate object. See Rotation schedules in the next section.

Rotation schedules¶

The Rotation schedule for all the SPK Pod’s certificates is configured for one hour.

Cluster namespace¶

It is suggested to install Cert Manager in a dedicated namespace, but it can run in any namespace. In this document, Cert Manager will install to the spk-cert-manager namespace. As mentioned earlier, Cert Manager uses the ClusterIssuer object to sign certificate requests across all cluster namespaces. Prior to installing the Cert Manager in a new namespace, refer to the Changing namespaces section of this document.

Requirements¶

Ensure you have:

Installed the SPK Software.
A Linux based workstation with Helm installed.

Important: Cert Manager requires the CRDs prefixed with f5-certmgr- provided in the f5-spk-crds-common tarball.

Procedures¶

Cert Manager¶

Use the following steps to install the SPK Cert Manager Pods.

Change into the directory containing the latest SPK Software, and list the f5-cert-manager Helm chart:
```
cd spkinstall; ls -1 tar | grep cert-manager
```
```
f5-cert-manager-0.22.10.tgz
```

Create a Helm values file named cert-manager-values.yaml, and set the image.repository parameters:

In this example, Helm pulls the Cert Manager images from registry.com.

image:
  repository: "registry.com"

webhook:
  image:
    repository: "registry.com"

cainjector:
  image:
    repository: "registry.com"

startupapicheck:
  image:
    repository: "registry.com"

init_container:
  image:
    repository: "registry.com"

In cert-manager-values.yaml file set the serviceAccount.create parameter:

Note: The serviceAccount will not be created by default.
```
serviceAccount:
  create: false
  name: default
```

If you enabled the Fluentd Logging collector, set the following parameters:

Note: Set the image.repository parameter to your local container registry, and the fluentd.host parameter to the Fluentd container Project.

logging_sidecar:
  enabled: true
  image:
    repository: "registry.com"
    name: f5-fluentbit
    tag: v0.4.1

  fluentd:
    host: f5-toda-fluentd.spk-utilities.svc.cluster.local.

Create a new namespace for the Cert Manager Pods:

Note: A new namespace is not required, and used only for easier Pod management.
```
oc create ns spk-cert-manager
```
Add the f5-cert-manager serviceAccount to the Project’s privileged security context constraint (SCC):
```
oc adm policy add-scc-to-user privileged -n <project> -z <serviceaccount>
```
In this example, the f5-cert-manager serviceAccount is added to the spk-cert-manager Project’s privileged SCC:
```
oc adm policy add-scc-to-user privileged -n spk-cert-manager -z default
```
To pull the imager from a secured registry, configure the respective imagePullSecrets for the f5-cert-manager.
- Configure the secret to default service account in spk-cert-manager namespace.
```
$ oc secrets link default <pull_secret_name> -n spk-cert-manager --for=pull
```
  Note: Ensure that the secret is in spk-cert-manager namespace as well.
- Configure the secret values in the values file.
```
global:
  imagePullSecrets:
    - name: pull_secret_name
```

Install the Cert Manager Pods using the following command syntax:

helm install <release> tar/<helm-chart>.tgz -f <values>.yaml -n <namespace>

For example:

helm install f5-certificate-manager tar/f5-cert-manager-0.22.10.tgz \
-f cert-manager-values.yaml -n spk-cert-manager

Verify the status of the Cert Manager Pods:

oc get pods -n spk-cert-manager

In this example, the f5-cert-manager, f5-cert-manager-cainjector, and f5-cert-manager-webhook are Running.

NAME                                          READY   STATUS    
f5-cert-manager-cainjector-5cfbf4ff75-drmh7   1/1     Running   
f5-cert-manager-cbfc74b4d-kskjx               1/1     Running   
f5-cert-manager-webhook-58bf4b7b76-bcn4p      1/1     Running   

Verify the list of all the ClusterIssuers:

oc get clusterissuers.cm.f5co.k8s.f5net.com

In this example, the ClusterIssuer is READY:

NAME                  READY     AGE
default-cert-issuer   True      4h33m

OTEL Collectors¶

The OTEL Collectors receive data from the SPK Pods and forward it to 3rd party visualization applications such as Prometheus. Cert Manager creates SSL/TLS certificates for the receiving side of the OTEL Collectors, but not for the sending side. You can utilize Cert Manager to create required certificates for OTEL to communicate with third party applications such as Prometheus. You can also manually create Kubernetes Secrets instead of using Cert Manager.

Copy the OTEL Certificate objects into a YAML file:

apiVersion: cm.f5co.k8s.f5net.com/v1
kind: Certificate
metadata:
  name: external-otelsvr
spec:
  subject:
    countries:
      - US
    provinces:
      - Washington
    localities:
      - Seattle
    organizations:
      - F5 Networks
    organizationalUnits:
      - PD
  emailAddresses:
    - clientcert@f5net.com
  commonName: f5net.com
  # SecretName is the name of the secret resource that will be automatically created and managed by this Certificate resource.
  # It will be populated with a private key and certificate, signed by the denoted issuer.
  secretName: external-otelsvr-secret
  # IssuerRef is a reference to the issuer for this certificate.
  issuerRef:
    name: default-cert-issuer
    kind: ClusterIssuer
  # Lifetime of the Certificate is 360 days.
  duration: 8640h
  privateKey:
    rotationPolicy: Always
    encoding: PKCS1
    algorithm: RSA
    size: 4096
  revisionHistoryLimit: 10
---
apiVersion: cm.f5co.k8s.f5net.com/v1
kind: Certificate
metadata:
  name: external-f5ingotelsvr
spec:
  subject:
    countries:
      - US
    provinces:
      - Washington
    localities:
      - Seattle
    organizations:
      - F5 Networks
    organizationalUnits:
      - PD
  emailAddresses:
    - clientcert@f5net.com
  commonName: f5net.com
  # SecretName is the name of the secret resource that will be automatically created and managed by this Certificate resource.
  # It will be populated with a private key and certificate, signed by the denoted issuer.
  secretName: external-f5ingotelsvr-secret
  # IssuerRef is a reference to the issuer for this certificate.
  issuerRef:
    name: default-cert-issuer
    kind: ClusterIssuer
  # Lifetime of the Certificate is 360 days.
  duration: 8640h
  privateKey:
    rotationPolicy: Always
    encoding: PKCS1
    algorithm: RSA
    size: 4096
  revisionHistoryLimit: 10

Install the Certificate objects to the OTEL Collector Project:

In this example, the Certificates install to the spk-ingress Project:
```
oc apply -f otel-certificates.yaml -n spk-ingress
```

The output should indicate the Certificates are created:

certificate.cm.f5co.k8s.f5net.com/external-otelsvr created
certificate.cm.f5co.k8s.f5net.com/external-f5ingotelsvr created

If the Prometheus scheme parameter is set to https (the default is http), you must also set the insecure_skip_verify parameter set to true. View the example ConfigMap template here.
Continue to the Next steps section.

Next steps¶

Continue with the next step of the installation process described in the Getting Started guide:

Fluentd Logging - Centralize logging data sent from each of the SPK Pods.
OTEL Collectors - Optional: Collect and view statistics from the SPK Pods.
dSSM Database - Optional: Store session-state data for the AFM and TMM Pods.
SPK CWC - Required: Install the Cluster Wide Controller to enable gathering SPK software telemetry.

Changing Namespaces¶

Prior to reinstalling the SPK Cert Manager to a different namespace, ensure you delete the currently installed Secrets.

Uninstall the Cert Manager:
```
helm uninstall <release> -n <namespace>
```
In this example, the Cert Manager release named f5-certificate-manager is in the spk-cert-manager namespace.
```
helm uninstall f5-certificate-manager -n spk-cert-manager 
```

List the Cert Manager Secrets:

oc get secrets -n spk-cert-manager

NAME                         TYPE                DATA
ca-key-pair                  kubernetes.io/tls   2 
f5-cert-manager-webhook-ca   Opaque              3

Delete the Secrets:

oc delete secret ca-key-pair -n spk-cert-manager

oc delete secret f5-cert-manager-webhook-ca -n spk-cert-manager

The command output should indicate the Secret is deleted.

secret "ca-key-pair" deleted

secret "f5-cert-manager-webhook-ca" deleted

Feedback¶

Provide feedback to improve this document by emailing spkdocs@f5.com.

Supplemental Information¶

The list of commands used to create the Secrets.
Introduction to gRPC
Kubernetes Secrets

Previous Next