From d6a72a14163ea3a164b0341aef1967677b2fb4fb Mon Sep 17 00:00:00 2001 From: Kirby Chin <37311900+kabicin@users.noreply.github.com> Date: Wed, 22 May 2024 17:38:53 -0400 Subject: [PATCH 1/5] Document the operator ConfigMap and how to change cert duration --- doc/user-guide-v1.adoc | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/user-guide-v1.adoc b/doc/user-guide-v1.adoc index 9dab63efd..52c9177dc 100644 --- a/doc/user-guide-v1.adoc +++ b/doc/user-guide-v1.adoc @@ -323,6 +323,40 @@ If the `.status.conditions.type` Ready type does not have a status of `True`, se The value of the `.status.versions.reconciled` parameter is the version of the operand that is deployed into the cluster after the reconcile loop completes. +[[operator-config-map]] +=== Operator ConfigMap + +The `ConfigMap` named `open-liberty-operator` is used for configuring Liberty operator managed resources. It is created once when the operator starts and is located in the operator's installed namespace. + +NOTE: For OCP users, the `AllNamespaces` install mode designates the namespace `openshift-operators` as the operator's installed namespace by default. + +This is a sample operator `ConfigMap` that would get generated when the operator is installed and running in the `test-namespace` namespace. + +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: open-liberty-operator + namespace: test-namespace +data: + certManagerCACertDuration: 8766h + certManagerCertDuration: 2160h + defaultHostname: '' +---- + +And here is the set of descriptions corresponding to each configurable field. + +.Operator ConfigMap data fields +|=== +| Field | Description +| `certManagerCACertDuration` | For cert-manager users, it is the CA Certificate's duration before renewal. The default value is `8766h` (1 year). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. +| `certManagerCertDuration` | For cert-manager users, it is the Certificate's duration before renewal. The default value is `2160h` (90 days). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. +| `defaultHostname` | The default hostname for the `OpenLibertyApplication` Route or Ingress URL when `.spec.expose` is set to `true`. To learn more about this field see link:#expose-applications-externally[Expose applications externally]. +|=== + + + === Operator configuration examples [[operator-configuration-examples]] Open Liberty Operator builds upon link:#common-component-documentation[components] from the generic link:++https://github.com/application-stacks/runtime-component-operator++[Runtime Component Operator] and provides additional features to customize your Open Liberty applications. @@ -1108,7 +1142,7 @@ To expose an application externally with Ingress in a non-Knative deployment, co 1. To use the `Ingress` resource to expose your cluster, install an `Ingress` controller such a Nginx or Traefik. 2. Ensure that a `Route` resource is not on the cluster. The Ingress resource is created only if the `Route` resource is not available on the cluster. -3. To use the `Ingress` resource, set the `defaultHostName` variable in the `open-liberty-operator` `ConfigMap` object to a hostname such as `mycompany.com`. +3. To use the `Ingress` resource, set the `defaultHostName` variable in the link:#operator-config-map[Operator ConfigMap] object to a hostname such as `mycompany.com`. 4. Enable TLS. Generate a certificate and specify the secret that contains the certificate with the `.spec.route.certificateSecretRef` field. + [source,yaml] @@ -1442,6 +1476,10 @@ When certificate manager is installed on the cluster, the service certificate is The operator creates a certificate authority (CA) `Issuer` instance to be shared by applications within a single namespace. The secret (or issuer) must be created in the same namespace as the `OpenLibertyApplication`. The issuer is used to generate a service certificate for each application that is mounted into the pod. The `tls.crt`, `tls.key`, and `ca.crt` files are mounted to the pod. The location is set by the `TLS_DIR` environment variable. The same secret (or issuer) is used for all instances of the application in the namespace. +By default, the Certificate requested by Liberty Operator is valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration, so the rotation will happen every 30 days by default. + +The default 90 days duration can be changed by updating the value of `certManagerCertDuration` in the link:#operator-config-map[Operator ConfigMap]. This global configuration applies to all applications managed by Liberty Operator. + ==== Generating certificates with certificate manager (existing certificate scenario) By default, the operator creates its own certificate authority (CA) for issuing service certificates. However, you can use your own CA certificate. To use your CA certificate, create a Kubernetes secret named `olo-custom-ca-tls`. This secret must contain the CA's `tls.crt` and `tls.key` file. After this secret is provided, the operator reissues certificates for the service by using the provided CA. From fa52e306355a62a8be6e56d7ad162bda13c087cd Mon Sep 17 00:00:00 2001 From: Kirby Chin <37311900+kabicin@users.noreply.github.com> Date: Thu, 23 May 2024 09:52:05 -0400 Subject: [PATCH 2/5] Update user-guide-v1.adoc --- doc/user-guide-v1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user-guide-v1.adoc b/doc/user-guide-v1.adoc index 52c9177dc..dbd9e3953 100644 --- a/doc/user-guide-v1.adoc +++ b/doc/user-guide-v1.adoc @@ -328,7 +328,7 @@ The value of the `.status.versions.reconciled` parameter is the version of the o The `ConfigMap` named `open-liberty-operator` is used for configuring Liberty operator managed resources. It is created once when the operator starts and is located in the operator's installed namespace. -NOTE: For OCP users, the `AllNamespaces` install mode designates the namespace `openshift-operators` as the operator's installed namespace by default. +NOTE: For OCP users, the `AllNamespaces` install mode designates `openshift-operators` as the operator's installed namespace. This is a sample operator `ConfigMap` that would get generated when the operator is installed and running in the `test-namespace` namespace. From ba7722fb29c64ecdf2d1dd6776c98996aa80c1d4 Mon Sep 17 00:00:00 2001 From: Kirby Chin <37311900+kabicin@users.noreply.github.com> Date: Thu, 23 May 2024 11:16:01 -0400 Subject: [PATCH 3/5] Update user-guide-v1.adoc --- doc/user-guide-v1.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/user-guide-v1.adoc b/doc/user-guide-v1.adoc index dbd9e3953..ee2dd3d52 100644 --- a/doc/user-guide-v1.adoc +++ b/doc/user-guide-v1.adoc @@ -350,8 +350,8 @@ And here is the set of descriptions corresponding to each configurable field. .Operator ConfigMap data fields |=== | Field | Description -| `certManagerCACertDuration` | For cert-manager users, it is the CA Certificate's duration before renewal. The default value is `8766h` (1 year). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. -| `certManagerCertDuration` | For cert-manager users, it is the Certificate's duration before renewal. The default value is `2160h` (90 days). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. +| `certManagerCACertDuration` | The cert-manager issued CA certificate's duration before expiry in link:++https://pkg.go.dev/time#ParseDuration++[Go `time.Duration`] string format. The default value is `8766h` (1 year). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. +| `certManagerCertDuration` | The cert-manager issued service certificate's duration before expiry in link:++https://pkg.go.dev/time#ParseDuration++[Go `time.Duration`] string format. The default value is `2160h` (90 days). To learn more about this field see link:#generating-certificates-with-certificate-manager[Generating certificates with certificate manager]. | `defaultHostname` | The default hostname for the `OpenLibertyApplication` Route or Ingress URL when `.spec.expose` is set to `true`. To learn more about this field see link:#expose-applications-externally[Expose applications externally]. |=== @@ -1476,9 +1476,9 @@ When certificate manager is installed on the cluster, the service certificate is The operator creates a certificate authority (CA) `Issuer` instance to be shared by applications within a single namespace. The secret (or issuer) must be created in the same namespace as the `OpenLibertyApplication`. The issuer is used to generate a service certificate for each application that is mounted into the pod. The `tls.crt`, `tls.key`, and `ca.crt` files are mounted to the pod. The location is set by the `TLS_DIR` environment variable. The same secret (or issuer) is used for all instances of the application in the namespace. -By default, the Certificate requested by Liberty Operator is valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration, so the rotation will happen every 30 days by default. +By default, the cert-manager certificates requested by Liberty Operator are valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration prior to expiry, so the rotation will happen every 60 days by default. -The default 90 days duration can be changed by updating the value of `certManagerCertDuration` in the link:#operator-config-map[Operator ConfigMap]. This global configuration applies to all applications managed by Liberty Operator. +The default 90 days duration can be changed by updating the value of `certManagerCertDuration` and `certManagerCACertDuration` in the link:#operator-config-map[Operator ConfigMap] (global configuration) and must be specified in link:++https://pkg.go.dev/time#ParseDuration++[Go `time.Duration`] string format. The `certManagerCertDuration` and `certManagerCACertDuration` fields are the durations before expiry for the cert-manager issued service certificate and CA, respectively. This global configuration applies to all applications managed by Liberty Operator. ==== Generating certificates with certificate manager (existing certificate scenario) From 9c4aec7ea42a70353fc3760c0508f1b0173f0920 Mon Sep 17 00:00:00 2001 From: Kirby Chin <37311900+kabicin@users.noreply.github.com> Date: Thu, 23 May 2024 11:42:33 -0400 Subject: [PATCH 4/5] Add observedGeneration note --- doc/user-guide-v1.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/user-guide-v1.adoc b/doc/user-guide-v1.adoc index ee2dd3d52..0d974f6d9 100644 --- a/doc/user-guide-v1.adoc +++ b/doc/user-guide-v1.adoc @@ -317,12 +317,15 @@ status: svcCertSecretName: my-liberty-app-svc-tls-ocp versions: reconciled: 1.0.0 + observedGeneration: 1 ---- If the `.status.conditions.type` Ready type does not have a status of `True`, see link:++troubleshooting.adoc++[Troubleshooting Open Liberty operators]. The value of the `.status.versions.reconciled` parameter is the version of the operand that is deployed into the cluster after the reconcile loop completes. +At the end of the reconcile loop, the operator will also update the `.status.observedGeneration` parameter to match the value of `.metadata.generation`. + [[operator-config-map]] === Operator ConfigMap From fde7a6748dc5add6e94ae5c19966d04d1de3884d Mon Sep 17 00:00:00 2001 From: Kirby Chin <37311900+kabicin@users.noreply.github.com> Date: Thu, 23 May 2024 15:54:55 -0400 Subject: [PATCH 5/5] Update user-guide-v1.adoc --- doc/user-guide-v1.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user-guide-v1.adoc b/doc/user-guide-v1.adoc index 0d974f6d9..fcc6f7d5f 100644 --- a/doc/user-guide-v1.adoc +++ b/doc/user-guide-v1.adoc @@ -1479,7 +1479,7 @@ When certificate manager is installed on the cluster, the service certificate is The operator creates a certificate authority (CA) `Issuer` instance to be shared by applications within a single namespace. The secret (or issuer) must be created in the same namespace as the `OpenLibertyApplication`. The issuer is used to generate a service certificate for each application that is mounted into the pod. The `tls.crt`, `tls.key`, and `ca.crt` files are mounted to the pod. The location is set by the `TLS_DIR` environment variable. The same secret (or issuer) is used for all instances of the application in the namespace. -By default, the cert-manager certificates requested by Liberty Operator are valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration prior to expiry, so the rotation will happen every 60 days by default. +By default, the cert-manager certificates requested by Liberty Operator are valid for 90 days (duration), but the rotation happens well before that. The default renew-before period is 1/3 of the duration prior to expiry, so the rotation will happen at 60 days by default. The default 90 days duration can be changed by updating the value of `certManagerCertDuration` and `certManagerCACertDuration` in the link:#operator-config-map[Operator ConfigMap] (global configuration) and must be specified in link:++https://pkg.go.dev/time#ParseDuration++[Go `time.Duration`] string format. The `certManagerCertDuration` and `certManagerCACertDuration` fields are the durations before expiry for the cert-manager issued service certificate and CA, respectively. This global configuration applies to all applications managed by Liberty Operator.