SPK Secrets¶
Overview¶
The SPK Controller, Service Proxy Traffic Management Microkernel (TMM), and optional OTEL Collectors communicate over secure channels using the gRPC (remote procedure call) framework. To secure the gRPC channel, SSL/TLS keys and certificates must be generated and stored as Secrets in the cluster.
Note: The gRPC channel is established over TCP service port 8750.
This document guides you through understanding, generating and installing the SPK Secrets.
Validity period¶
SSL/TLS certificates are valid for a specific period of time, and once they expire, secure connections fail when attempting to validate the certificate. When creating new SSL/TLS certificates for the gRPC channel, it is recommended that you choose a period of one year, or two years to avoid connection failures.
Example SSL Certificate validity period:
Validity
Not Before: Jan 1 10:30:00 2021 GMT
Not After : Jan 1 10:30:00 2022 GMT
Updating Secrets¶
When planning to replace previously installed SPK Secrets, you must restart the Controller and Service Proxy TMM Pods to begin using the new Secrets. To replace existing Secrets, refer to the Restarting section of this guide.
Important: Restarting the Service Proxy TMM Pods impacts traffic processing.
Procedures¶
Creating the Secrets¶
Use the following steps to generate the gRPC SSL/TLS keys and certificates.
Note: The commands used to generate the Secrets can be downloaded here.
Change into the directory with the SPK files:
cd <directory>
In this example, the SPK files are in the spkinstall directory:
cd spkinstall
Create a new directory for the Secret SSL/TLS keys and certificates, and change into the directory:
mkdir <directory>
cd <directory>
In this example, a new directory named grpc_secrets is created and changed into:
mkdir grpc_secrets
cd grpc_secrets
Create the gRPC Certificate Authority (CA) signing key and certificate:
Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.
openssl genrsa -out grpc-ca.key 4096
openssl req -x509 -new -nodes -key grpc-ca.key -sha256 -days 365 -out grpc-ca.crt \ -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=Dev/CN=ca"
The following code creates a new file named server.ext with the required SSL/TLS attributes:
echo "[req_ext]" > server.ext echo " " >> server.ext echo "subjectAltName = @alt_names" >> server.ext echo " " >> server.ext echo "[alt_names]" >> server.ext echo " " >> server.ext echo "DNS.1 = grpc-svc" >> server.ext echo "DNS.2 = otel-collector" >> server.ext
The server.ext file should contain the following SSL/TLS attributes:
[req_ext] subjectAltName = @alt_names [alt_names] DNS.1 = grpc-svc DNS.2 = otel-collector
Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed certificate for the Controller and TMM channel:
Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.
openssl genrsa -out grpc-server.key 4096
openssl req -new -key grpc-server.key -out grpc-server.csr \ -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
openssl x509 -req -in grpc-server.csr -CA grpc-ca.crt -CAkey grpc-ca.key \ -CAcreateserial -out grpc-server.crt -extensions req_ext -days 365 -sha256 \ -extfile server.ext
Create the gRPC server SSL/TLS key, certificate signing request (CSR), and signed certificate for the Controller, TMM and OTEL channel:
Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.
openssl genrsa -out grpc-otel-server.key 4096
openssl req -new -key grpc-otel-server.key -out grpc-otel-server.csr \ -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
openssl x509 -req -in grpc-otel-server.csr -CA grpc-ca.crt -CAkey grpc-ca.key \ -set_serial 101 -outform PEM -out grpc-otel-server.crt -extensions req_ext -days 365 \ -sha256 -extfile server.ext
The following code creates a new file named client.ext with the required SSL/TLS attributes:
echo "[req_ext]" > client.ext echo " " >> client.ext echo "subjectAltName = @alt_names" >> client.ext echo " " >> client.ext echo "[alt_names]" >> client.ext echo " " >> client.ext echo "email.1 = clientcert@f5net.com" >> client.ext
The client.ext file should contain the following SSL/TLS attributes:
[req_ext] subjectAltName = @alt_names [alt_names] email.1 = clientcert@f5net.com
Create the gRPC client key, CSR and signed certificate for the Controller and TMM channel:
Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.
openssl genrsa -out grpc-client.key 4096
openssl req -new -key grpc-client.key -out grpc-client.csr \ -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
openssl x509 -req -in grpc-client.csr -CA grpc-ca.crt -CAkey grpc-ca.key \ -set_serial 101 -outform PEM -out grpc-client.crt -extensions req_ext -days 365 \ -sha256 -extfile client.ext
Create the gRPC client key, CSR and signed certificate for the Controller, TMM and OTEL channel:
Note: Adapt the number of -days the certificate will be valid, and the -subj information for your environment.
openssl genrsa -out grpc-otel-client.key 4096
openssl req -new -key grpc-otel-client.key -out grpc-otel-client.csr \ -subj "/C=US/ST=WA/L=Seattle/O=F5/OU=PD/CN=f5net.com"
openssl x509 -req -in grpc-otel-client.csr -CA grpc-ca.crt -CAkey grpc-ca.key \ -set_serial 101 -outform PEM -out grpc-otel-client.crt -extensions req_ext -days 365 \ -sha256 -extfile client.ext
Installing the Secrets¶
Use the following steps to encode, and store the SSL/TLS keys and certificates as Secrets in the cluster.
The following code performs a Base64 encoding of the keys and certificates:
openssl base64 -A -in grpc-ca.crt -out grpc-ca-encode.crt openssl base64 -A -in grpc-server.crt -out grpc-server-encode.crt openssl base64 -A -in grpc-client.crt -out grpc-client-encode.crt openssl base64 -A -in grpc-server.key -out grpc-server-encode.key openssl base64 -A -in grpc-ca.key -out grpc-ca-encode.key openssl base64 -A -in grpc-client.key -out grpc-client-encode.key openssl base64 -A -in grpc-otel-client.crt -out grpc-otel-client-encode.crt openssl base64 -A -in grpc-otel-server.crt -out grpc-otel-server-encode.crt openssl base64 -A -in grpc-otel-client.key -out grpc-otel-client-encode.key openssl base64 -A -in grpc-otel-server.key -out grpc-otel-server-encode.key
The following code creates the K8S Secret object used to store SSL/TLS keys:
Important: The syntax in the bottom three lines; grpc-svc.key, priv.key, and f5-ing-demo-f5ingress.key, must be set as in the example.
echo "apiVersion: v1" > keys-secret.yaml echo "kind: Secret" >> keys-secret.yaml echo "metadata:" >> keys-secret.yaml echo " name: keys-secret" >> keys-secret.yaml echo "data:" >> keys-secret.yaml echo -n " priv.key: " >> keys-secret.yaml; cat grpc-ca-encode.key >> keys-secret.yaml echo "" >> keys-secret.yaml echo -n " grpc-svc.key: " >> keys-secret.yaml; cat grpc-server-encode.key >> keys-secret.yaml echo "" >> keys-secret.yaml echo -n " f5-ing-demo-f5ingress.key: " >> keys-secret.yaml; cat grpc-client-encode.key >> keys-secret.yaml echo "" >> keys-secret.yaml echo -n " grpc-otel-client.key: " >> keys-secret.yaml; cat grpc-otel-client-encode.key >> keys-secret.yaml echo "" >> keys-secret.yaml echo -n " grpc-otel-server.key: " >> keys-secret.yaml; cat grpc-otel-server-encode.key >> keys-secret.yaml
The following code creates the K8S Secret object used to store the SSL/TLS certificates:
Important: The syntax in the bottom three lines; grpc-svc.crt, ca_root.crt, and f5-ing-demo-f5ingress.crt, must be set as in the example.
echo "apiVersion: v1" > certs-secret.yaml echo "kind: Secret" >> certs-secret.yaml echo "metadata:" >> certs-secret.yaml echo " name: certs-secret" >> certs-secret.yaml echo "data:" >> certs-secret.yaml echo -n " ca_root.crt: " >> certs-secret.yaml; cat grpc-ca-encode.crt >> certs-secret.yaml echo "" >> certs-secret.yaml echo -n " grpc-svc.crt: " >> certs-secret.yaml; cat grpc-server-encode.crt >> certs-secret.yaml echo "" >> certs-secret.yaml echo -n " f5-ing-demo-f5ingress.crt: " >> certs-secret.yaml; cat grpc-client-encode.crt >> certs-secret.yaml echo "" >> certs-secret.yaml echo -n " grpc-otel-client.crt: " >> certs-secret.yaml; cat grpc-otel-client-encode.crt >> certs-secret.yaml echo "" >> certs-secret.yaml echo -n " grpc-otel-server.crt: " >> certs-secret.yaml; cat grpc-otel-server-encode.crt >> certs-secret.yaml
Create a new Project for the Controller and Service Proxy deployments:
oc new-project <project>
In this example, a new Project named spk-ingress is created:
oc new-project spk-ingress
Add the ServiceAccount for the TMM Pod to the privileged security context constraint (SCC):
A. By default, TMM uses the default ServiceAccount:
Note: See step 6 and to add a custom ServiceAccount to the privileged SCC.
oc adm policy add-scc-to-user privileged -n <project> -z default
In this example, the default ServiceAccount is added to the privileged SCC for the spk-ingress Project:
oc adm policy add-scc-to-user privileged -n spk-ingress -z default
B. To use a custom ServiceAccount, you must also update the SPK Controller Helm values file:
In this example, the custom spk-tmm ServiceAccount is added to the privileged SCC.
oc adm policy add-scc-to-user privileged -n spk-ingress -z spk-tmm
In this example, the custom spk-tmm ServiceAccount is added to the Helm values file.
tmm: serviceAccount: name: spk-tmm
Install the Secret key and certificate objects:
In this example, the Secrets install to the spk-ingress Project:
oc apply -f keys-secret.yaml -n spk-ingress oc apply -f certs-secret.yaml -n spk-ingress
The command responses should state the Secrets have been created:
secret/keys-secret created secret/certs-secret created
The new Secrets will now be used to secure the gRPC channel.
Next step¶
Continue to one of the following guides listed by installation precedence:
- Optional: Install the Fluentd Logging collector to centralize SPK Pod logging.
- Optional: Install the OTEL Collectors to visualize SPK Pod statistics.
- Optional: Install the dSSM Database to store session-state information.
- Required: Install the SPK Controller and Service Proxy TMM Pods.
Restarting¶
This procedure assumes that you have deployed the Controller and Service Proxy Pods, and have created a new set of Secrets to replace the existing Secrets. New Secrets will not be used until the Controller and TMM Pods have been restarted.
Important: Restarting the Service Proxy TMM Pods impacts traffic processing.
Switch to the Service Proxy TMM Project:
oc project <project>
In this example, the spk-ingress Project is selected:
oc project spk-ingress
Obtain the name and number of SPK Controller and Service Proxy TMM Pods:
oc get deploy
In this example, there is 1 Controller and 3 Service Proxy TMM Pods:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 3/3 3
Scale the number of Service Proxy Pods to 0:
oc scale deploy f5-tmm --replicas=0
Ensure 0 of the f5-tmm Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 0/0 0
Scale the TMM Pods back to the previous number:
oc scale deploy f5-tmm --replicas=<number>
In this example the TMM Pods are scaled back to 3:
oc scale deployment f5-tmm --replicas=3
Ensure 3 of the f5-tmm Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 3/3 3
Scale the Controller to 0:
oc scale deployment <name> --replicas=0
For example:
oc scale deploy f5ingress-f5ingress --replicas=0
Ensure 0 of the Controller Pods are AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 0/0 0 f5-tmm 3/3 3
Scale the Controller back to the previous number:
oc scale deployment <name> --replicas=1
In this example the Controller is scaled back to 1:
oc scale deployment f5ingress-f5ingress --replicas=1
Ensure the Controller Pod is AVAILABLE:
NAME READY AVAILABLE f5ingress-f5ingress 1/1 1 f5-tmm 3/3 3
The new Secrets should now be used to secure the gRPC channel.
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