From 5731beea8c71c62188fec79086d569fc86fa03ca Mon Sep 17 00:00:00 2001 From: Bobby Iliev Date: Thu, 28 Nov 2024 22:21:37 +0200 Subject: [PATCH 1/2] Adding a simple TLS setup guide --- docs/operator-tls-setup.md | 221 +++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 docs/operator-tls-setup.md diff --git a/docs/operator-tls-setup.md b/docs/operator-tls-setup.md new file mode 100644 index 0000000..aee7316 --- /dev/null +++ b/docs/operator-tls-setup.md @@ -0,0 +1,221 @@ +# Configuring TLS for the Materialize Operator + +After [installing the Materialize Operator](./operator-setup.md), follow these steps to configure TLS for secure communication. + +## Prerequisites + +- Materialize Operator installed on your cluster +- cert-manager v1.13.0+ installed +- `kubectl` configured to interact with your cluster + +## Install cert-manager + +If cert-manager is not already installed on your cluster, you can install it using the following command: + +```bash +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.0/cert-manager.yaml +``` + +Verify the installation: + +```bash +kubectl get pods -n cert-manager +``` + +## Configure Certificate Issuers + +1. Create the self-signed root certificate issuer (save as `certificate-issuers.yaml` file): + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: dns01 +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: intermediate-ca + namespace: materialize-environment +spec: + ca: + secretName: ca-key-pair +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: ca-key-pair + namespace: materialize-environment +spec: + isCA: true + commonName: materialize-ca + secretName: ca-key-pair + privateKey: + algorithm: ECDSA + size: 256 + issuerRef: + name: dns01 + kind: ClusterIssuer +``` + +2. Apply the configuration: + +```bash +kubectl apply -f certificate-issuers.yaml +``` + +3. Verify the issuers are ready: + +```bash +kubectl get clusterissuer dns01 +kubectl get issuer -n materialize-environment intermediate-ca +kubectl get certificate -n materialize-environment ca-key-pair +``` + +## Configure Materialize with TLS + +1. Update your Materialize Operator Helm values to include TLS configuration or create a new values file (save as `materialize-values-tls.yaml`): + +```yaml +# Existing values... + +# Add TLS configuration +tls: + defaultCertificateSpecs: + balancerdExternal: + dnsNames: + - balancerd + - balancerd.materialize-environment.svc.cluster.local # Change to your namespace + issuerRef: + name: dns01 + kind: ClusterIssuer + consoleExternal: + dnsNames: + - console + - console.materialize-environment.svc.cluster.local # Change to your namespace + issuerRef: + name: dns01 + kind: ClusterIssuer + internal: + issuerRef: + name: intermediate-ca + kind: Issuer +``` + +2. Update the Materialize Operator installation: + +```bash +helm upgrade materialize-operator misc/helm-charts/operator \ + -f materialize-values-tls.yaml +``` + +3. Create or update your Materialize environment (save as `materialize-environment-tls.yaml`): + +```yaml +apiVersion: materialize.cloud/v1alpha1 +kind: Materialize +metadata: + name: 12345678-1234-1234-1234-123456789012 + namespace: materialize-environment +spec: + environmentdImageRef: materialize/environmentd:v0.126.0 # Use your desired version + backendSecretName: materialize-backend + requestRollout: 22222222-2222-2222-2222-222222222222 + forceRollout: 33333333-3333-3333-3333-333333333333 + balancerdExternalCertificateSpec: + dnsNames: + - balancerd + - balancerd.materialize-environment.svc.cluster.local + issuerRef: + name: dns01 + kind: ClusterIssuer + consoleExternalCertificateSpec: + dnsNames: + - console + - console.materialize-environment.svc.cluster.local + issuerRef: + name: dns01 + kind: ClusterIssuer + internalCertificateSpec: + issuerRef: + name: intermediate-ca + kind: Issuer +``` + +The `forceRollout` and `requestRollout` fields are used to trigger a rollout of the Materialize environment. They should be set to unique UUIDs. + +4. Apply the environment configuration: + +```bash +kubectl apply -f materialize-environment-tls.yaml +``` + +## Verify TLS Configuration + +1. Check certificate status: + +```bash +kubectl get certificates -n materialize-environment +kubectl get certificaterequests -n materialize-environment +``` + +You should see certificates being issued and ready: + +``` +# Certificates: +NAME READY SECRET AGE +ca-key-pair True ca-key-pair 4m21s +mztjut43kipm-balancerd-external True mztjut43kipm-balancerd-external-tls 43s +mztjut43kipm-console-external True mztjut43kipm-console-external-tls 3m15s +mztjut43kipm-environmentd-external True mztjut43kipm-environmentd-tls 43s + +# Certificate requests: +NAME APPROVED DENIED READY ISSUER REQUESTOR AGE +ca-key-pair-1 True True dns01 system:serviceaccount:cert-manager:cert-manager 4m30s +mztjut43kipm-balancerd-external-1 True True dns01 system:serviceaccount:cert-manager:cert-manager 52s +mztjut43kipm-console-external-1 True True dns01 system:serviceaccount:cert-manager:cert-manager 3m24s +mztjut43kipm-environmentd-external-1 True True intermediate-ca system:serviceaccount:cert-manager:cert-manager 52s +``` + +2. Verify the Materialize environment is running: + +```bash +kubectl get materializes -n materialize-environment +kubectl get pods -n materialize-environment +``` + +## Troubleshooting + +If certificates are not being issued: + +1. Check cert-manager logs: + +```bash +kubectl logs -n cert-manager -l app=cert-manager +``` + +2. Check certificate events: + +```bash +kubectl describe certificate -n materialize-environment +``` + +3. Check issuer status: + +```bash +kubectl describe clusterissuer dns01 +kubectl describe issuer intermediate-ca -n materialize-environment +``` + +If a certificate is stuck in a pending state: + +```bash +# Delete the failing certificate request +kubectl delete certificaterequest -n materialize-environment + +# Delete and recreate the issuer if needed +kubectl delete issuer intermediate-ca -n materialize-environment +kubectl apply -f certificate-issuers.yaml +``` From 1e49274af1d463a03ffb01797b0bec1cc16f3a64 Mon Sep 17 00:00:00 2001 From: Bobby Iliev Date: Mon, 2 Dec 2024 13:25:05 +0200 Subject: [PATCH 2/2] update TLS configuration steps --- docs/operator-tls-setup.md | 99 +++++++++----------------------------- 1 file changed, 22 insertions(+), 77 deletions(-) diff --git a/docs/operator-tls-setup.md b/docs/operator-tls-setup.md index aee7316..682088e 100644 --- a/docs/operator-tls-setup.md +++ b/docs/operator-tls-setup.md @@ -24,55 +24,14 @@ kubectl get pods -n cert-manager ## Configure Certificate Issuers -1. Create the self-signed root certificate issuer (save as `certificate-issuers.yaml` file): +Before configuring TLS for Materialize, you'll need to set up appropriate certificate issuers in your cluster. The specific configuration will depend on your environment and requirements. Please refer to the [cert-manager documentation](https://cert-manager.io/docs/configuration/) for detailed guidance on: -```yaml -apiVersion: cert-manager.io/v1 -kind: ClusterIssuer -metadata: - name: dns01 -spec: - selfSigned: {} ---- -apiVersion: cert-manager.io/v1 -kind: Issuer -metadata: - name: intermediate-ca - namespace: materialize-environment -spec: - ca: - secretName: ca-key-pair ---- -apiVersion: cert-manager.io/v1 -kind: Certificate -metadata: - name: ca-key-pair - namespace: materialize-environment -spec: - isCA: true - commonName: materialize-ca - secretName: ca-key-pair - privateKey: - algorithm: ECDSA - size: 256 - issuerRef: - name: dns01 - kind: ClusterIssuer -``` +- Choosing the right issuer type for your environment +- Configuring production-ready certificate issuers +- Setting up intermediate CAs if required +- Managing certificate lifecycle and renewal -2. Apply the configuration: - -```bash -kubectl apply -f certificate-issuers.yaml -``` - -3. Verify the issuers are ready: - -```bash -kubectl get clusterissuer dns01 -kubectl get issuer -n materialize-environment intermediate-ca -kubectl get certificate -n materialize-environment ca-key-pair -``` +Once you have configured your certificate issuers, you can proceed with the Materialize TLS configuration. ## Configure Materialize with TLS @@ -85,25 +44,21 @@ kubectl get certificate -n materialize-environment ca-key-pair tls: defaultCertificateSpecs: balancerdExternal: - dnsNames: - - balancerd - - balancerd.materialize-environment.svc.cluster.local # Change to your namespace - issuerRef: - name: dns01 - kind: ClusterIssuer + duration: 2160h # 90 days + renewBefore: 360h # 15 days + privateKey: + algorithm: ECDSA + size: 256 consoleExternal: - dnsNames: - - console - - console.materialize-environment.svc.cluster.local # Change to your namespace - issuerRef: - name: dns01 - kind: ClusterIssuer - internal: - issuerRef: - name: intermediate-ca - kind: Issuer + duration: 2160h # 90 days + renewBefore: 360h # 15 days + privateKey: + algorithm: ECDSA + size: 256 ``` +> Note: Configure only the fields that should be common across all Materialize environments. DNS names and secret templates should be configured per environment in the Materialize Custom Resource. + 2. Update the Materialize Operator installation: ```bash @@ -126,22 +81,12 @@ spec: forceRollout: 33333333-3333-3333-3333-333333333333 balancerdExternalCertificateSpec: dnsNames: - - balancerd - - balancerd.materialize-environment.svc.cluster.local - issuerRef: - name: dns01 - kind: ClusterIssuer + - mz-balancerd-prod.example.com + - mz-balancerd-prod-internal.example.com consoleExternalCertificateSpec: dnsNames: - - console - - console.materialize-environment.svc.cluster.local - issuerRef: - name: dns01 - kind: ClusterIssuer - internalCertificateSpec: - issuerRef: - name: intermediate-ca - kind: Issuer + - mz-console-prod.example.com + - mz-console-prod-internal.example.com ``` The `forceRollout` and `requestRollout` fields are used to trigger a rollout of the Materialize environment. They should be set to unique UUIDs.