THREESCALE-11395 Updated docs with watched secret changes

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.

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
 

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
 

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