From 1f3285e6913489bacb2f94fd50ee66ab39c94b0b Mon Sep 17 00:00:00 2001 From: Carl Kyrillos Date: Thu, 7 Nov 2024 17:13:09 -0500 Subject: [PATCH] THREESCALE-11395 Updated docs with watched secret changes --- doc/adding-apicast-custom-environments.md | 35 ++++++++++++----------- doc/adding-custom-policies.md | 29 +++++++------------ doc/apimanager-reference.md | 2 +- doc/development.md | 21 +++++++++++++- 4 files changed, 49 insertions(+), 38 deletions(-) diff --git a/doc/adding-apicast-custom-environments.md b/doc/adding-apicast-custom-environments.md index 8b09d532a..5f87402a7 100644 --- a/doc/adding-apicast-custom-environments.md +++ b/doc/adding-apicast-custom-environments.md @@ -1,8 +1,8 @@ ## Adding custom environments -Add custom environment loaded in all 3scale products. +Add custom environment(s) loaded in all 3scale products. -Here is an example of a policy that is loaded in all services: `custom_env.lua` +Here is an example of a environment that is loaded in all services: `custom_env.lua` ```lua local cjson = require('cjson') @@ -26,14 +26,24 @@ return { ### Prerequisites -* One or more custom environment in lua code. +* One or more custom environment(s) in lua code. ### Adding custom environment #### Create secret with the custom environment content ``` -oc create secret generic custom-env-1 --from-file=./env11.lua +oc create secret generic custom-env-1 --from-file=./custom_env.lua +``` + +By default, content changes in the secret will not be noticed by the 3scale operator. +The 3scale operator allows the monitoring of secret changes, this can be achieved by adding the +`apimanager.apps.3scale.net/watched-by=apimanager` label to the required secret. +With the label in place, when the content of the secret changes, the operator will update the deployment of the apicast +where that secret is used (staging or production). +The operator will not take *ownership* of the secret in any way. +``` +oc label secret custom-env-1 apimanager.apps.3scale.net/watched-by=apimanager ``` **NOTE**: a secret can host multiple custom environments. The operator will load each one of them. @@ -52,13 +62,13 @@ spec: productionSpec: customEnvironments: - secretRef: - name: env1 + name: custom-env-1 - secretRef: - name: env2 + name: custom-env-2 stagingSpec: customEnvironments: - secretRef: - name: env3 + name: custom-env-3 ``` **NOTE**: Multiple custom environment secrets can be added. The operator will load each one of them. @@ -71,13 +81,4 @@ oc apply -f apimanager.yaml The APIManager custom resource allows adding multiple custom environments per secret. -**NOTE**: If secret does not exist, the operator would mark the custom resource as failed. The Deployment object would fail if secret does not exist. - -*NOTE*: Once apicast has been deployed, the content of the secret should not be updated externally. -If the content of the secret is updated externally, after apicast has been deployed, the container can automatically see the changes. -However, apicast has the environment already loaded and it does not change the behavior. - -If the custom environment content needs to be changed, there are two options: - -* [**recommended way**] Create another secret with a different name and update the APIManager custom resource field `customEnvironments[].secretRef.name`. The operator will trigger a rolling update loading the new custom environment content. -* Update the existing secret content and redeploy apicast turning `spec.apicast.productionSpec.replicas` or `spec.apicast.stagingSpec.replicas` to 0 and then back to the previous value. +**NOTE**: If the referenced secret does not exist, the operator will mark the APIManager CustomResource as failed. The apicast Deployment object will also fail if the referenced secret does not exist. \ No newline at end of file diff --git a/doc/adding-custom-policies.md b/doc/adding-custom-policies.md index f7a2766f7..0349bc325 100644 --- a/doc/adding-custom-policies.md +++ b/doc/adding-custom-policies.md @@ -6,7 +6,7 @@ for more info about creating custom policies. ### Prerequisites -* Custom policy metadata included in `apicast-policy.json` +* Custom policy metadata included in `apicast-policy.json`: ```json { @@ -21,9 +21,9 @@ for more info about creating custom policies. } } ``` -* Custom policy lua code. `init.lua` file is required. Optionally, add more lua files. For this specific example, `init.lua` and `example.lua` files will be shown. +* Custom policy lua code. The `init.lua` file is required. Optionally, add more lua files. For this specific example, `init.lua` and `example.lua` files are used. -`init.lua` +`init.lua`: ```lua return require('example') ``` @@ -101,7 +101,7 @@ With the label in place, when the content of the secret changes, the operator wi where that secret is used (staging or production). The operator will not take *ownership* of the secret in any way. ``` -kubectl label secret custom-policy-example-1 apimanager.apps.3scale.net/watched-by=apimanager +oc label secret custom-policy-example-1 apimanager.apps.3scale.net/watched-by=apimanager ``` #### Configure and deploy APIManager CR with the custom policy @@ -120,21 +120,21 @@ spec: - name: custom-policy1 version: "0.1" secretRef: - name: custom-policy1-secret + name: custom-policy-example-1 - name: custom-policy2 version: "0.1" secretRef: - name: custom-policy2-secret + name: custom-policy-example-2 productionSpec: customPolicies: - name: custom-policy1 version: "0.1" secretRef: - name: custom-policy1-secret + name: custom-policy-example-1 - name: custom-policy2 version: "0.1" secretRef: - name: custom-policy2-secret + name: custom-policy-example-2 ``` ``` @@ -145,16 +145,7 @@ The APIManager custom resource allows adding multiple custom policies. **NOTE**: The tuple (`name`, `version`) has to be unique in the `customPolicies` array. -**NOTE**: If secret does not exist, the operator would mark the custom resource as failed. - -*NOTE*: Once the apicast has been deployed, the content of the secret should not be updated externally. -If the content of the secret is updated externally, after apicast has been deployed, the container can automatically see the changes. -However, apicast has the policy already loaded and it does not change the behavior. - -If the policy content needs to be changed, there are two options: - -* [recommended way] Create another secret with a different name and update the APIManager custom resource field `customPolicies[].secretRef.name`. The operator will trigger a rolling update loading the new policy content. -* Update the existing secret content and redeploy apicast turning `spec.apicast.productionSpec.replicas` (or `spec.apicast.stagingSpec.replicas`) to 0 and then back to the previous value. +**NOTE**: If secret does not exist, the operator will mark the APIManager CustomResource as failed. #### Add the custom policy metadata to 3scale policy registry @@ -219,7 +210,7 @@ spec: #### Adding the custom policy to a policy chain in 3scale Configure 3scale product to include the new custom policy in the gateway policy chain to be used by APIcast. -The custom policy needs to be added to the policy registry before adding it to some 3scale product's policy chain.. +The custom policy needs to be added to the policy registry before adding it to some 3scale product's policy chain. * Using the 3scale admin portal UI diff --git a/doc/apimanager-reference.md b/doc/apimanager-reference.md index f6dd9aca6..916a4fc54 100644 --- a/doc/apimanager-reference.md +++ b/doc/apimanager-reference.md @@ -214,7 +214,7 @@ By default, content changes in the secret will not be noticed by the 3scale oper The 3scale operator allows monitoring the secret for changes adding the `apimanager.apps.3scale.net/watched-by=apimanager` label. With that label in place, when the content of the secret is changed, the operator will get notified. Then, the operator will rollout apicast deployment to make the changes effective. -The operator will not take *ownership* of the secret in any way. +The operator will not take *ownership* of the watched secret in any way. ### APIcastTracingConfigSecret diff --git a/doc/development.md b/doc/development.md index 912f81627..6f542f4f4 100644 --- a/doc/development.md +++ b/doc/development.md @@ -19,7 +19,7 @@ * [Validate an operator bundle image](#validate-an-operator-bundle-image) * [Licenses management](#licenses-management) * [Adding manually a new license](#adding-manually-a-new-license) -* [Building and pushing 3scale component images](#building-and-pushing-3scale-component-images) +* [Adding new watched secrets](#adding-new-watched-secrets) Generated using [github-markdown-toc](https://github.com/ekalinin/github-markdown-toc) @@ -238,3 +238,22 @@ license_finder approval add github.com/golang/glog --decisions-file=doc/dependen [docker]:https://docs.docker.com/install/ [kubernetes]:https://kubernetes.io/ [oc]:https://github.com/openshift/origin/releases + +## Adding new watched secrets +After adding a new secret to the APIManager CRD make sure to also update the following files if you want the 3scale-operator to watch the new secret: +1. [apis/apps/v1alpha1/apimanager_types.go](../apis/apps/v1alpha1/apimanager_types.go) + - Add a new `GetXYZSecretRef()` function that returns the secret ref +2. [apis/apps/v1alpha1/apimanager_types.go](../apis/apps/v1alpha1/apimanager_types.go) + - Update the `Get3scaleSecretRefs()` to call the new `GetXYZSecretRef()` function from step 1 +3. [pkg/3scale/amp/operator/apicast_reconciler.go](../pkg/3scale/amp/operator/apicast_reconciler.go) + - Add the new secret to the `getSecretUIDs()` function +4. [pkg/3scale/amp/component/deployment_annotations.go](../pkg/3scale/amp/component/deployment_annotations.go) + - Add the new secret to the `getWatchedSecretAnnotations()` function +5. [pkg/3scale/amp/component/deployment_annotations.go](../pkg/3scale/amp/component/deployment_annotations.go) + - Add the new secret to the switch in the `HasSecretHashChanged()` function +6. pkg/3scale/amp/component/{component_name}.go + - Add a new const called `XYZSecretResverAnnotationPrefix` that can be referenced throughout the code + - The const should be in the `component` package but the exact file will depend on which deployment the new watched secret relates to. For example if the secret is relevant to the `apicast` deployments, the const belongs in [pkg/3scale/amp/component/apicast.go](../pkg/3scale/amp/component/apicast.go) +7. pkg/3scale/amp/component/{component_name}.go + - Add an annotation for the new watched secret to the relevant deployment's `.spec.template.metadata.annotations` + - The exact file that needs changing will depend on which deployment the new watched secret relates to. See the `StagingDeployment()` function in [pkg/3scale/amp/component/apicast.go](../pkg/3scale/amp/component/apicast.go) for an example