Merge pull request #614 from external-secrets/fix/docs

Improves Documentation. Removes controller reference

deploy/charts/external-secrets/README.md

@@ -36,6 +36,7 @@ The command removes all the Kubernetes components associated with the chart and
 |-----|------|---------|-------------|
 | affinity | object | `{}` |  |
 | concurrent | int | `1` | Specifies the number of concurrent ExternalSecret Reconciles external-secret executes at a time. |
+| controllerClass | string | `""` | If set external secrets will filter matching Secret Stores with the appropriate controller values. |
 | deploymentAnnotations | object | `{}` | Annotations to add to Deployment |
 | extraArgs | object | `{}` |  |
 | extraEnv | list | `[]` |  |

deploy/charts/external-secrets/templates/deployment.yaml

@@ -51,6 +51,9 @@ spec:
           {{- if .Values.scopedNamespace }}
           - --namespace={{ .Values.scopedNamespace }}
           {{- end }}
+          {{- if .Values.controllerClass }}
+          - --controller-class={{ .Values.controllerClass }}
+          {{- end }}
           {{- if .Values.concurrent }}
           - --concurrent={{ .Values.concurrent }}
           {{- end }}

deploy/charts/external-secrets/values.yaml

@@ -17,6 +17,10 @@ fullnameOverride: ""
 # than one instance of external-secrets operates at a time.
 leaderElect: false
 
+# -- If set external secrets will filter matching
+# Secret Stores with the appropriate controller values.
+controllerClass: ""
+
 # -- If set external secrets are only reconciled in the
 # provided namespace
 scopedNamespace: ""

docs/contributing-devguide.md

@@ -8,17 +8,28 @@ git clone https://github.com/external-secrets/external-secrets.git
 cd external-secrets
 ```
 
-If you want to run controller tests you also need to install kubebuilder's `envtest`:
+If you want to run controller tests you also need to install kubebuilder's `envtest`.
+
+The recommended way to do so is to install [setup-envtest](https://pkg.go.dev/sigs.k8s.io/controller-runtime/tools/setup-envtest)
+
+Here is an example on how to set it up:
 
 ```
-export KUBEBUILDER_TOOLS_VERSION='1.20.2' # check for latest version or a version that has support to what you are testing
+go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
+
+# list available versions
+setup-envtest list --os $(go env GOOS) --arch $(go env GOARCH)
+
+# To use a specific version
+setup-envtest use -p path 1.20.2
 
-curl -sSLo envtest-bins.tar.gz "https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-$KUBEBUILDER_TOOLS_VERSION-linux-amd64.tar.gz"
+#To set environment variables
+source <(setup-envtest use 1.20.2 -p env --os $(go env GOOS) --arch $(go env GOARCH))
 
-sudo mkdir -p /usr/local/kubebuilder
-sudo tar -C /usr/local/kubebuilder --strip-components=1 -zvxf envtest-bins.tar.gz
 ```
 
+for more information, please see [setup-envtest docs](https://github.com/kubernetes-sigs/controller-runtime/tree/master/tools/setup-envtest)
+
 ## Building & Testing
 
 The project uses the `make` build system. It'll run code generators, tests and
@@ -74,8 +85,15 @@ kind create cluster --name external-secrets
 export TAG=v2
 export IMAGE=eso-local
 
+#For building in linux
 docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=linux
 
+#For building in MacOS (OSX)
+#docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=darwin
+
+#For building in ARM
+#docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=arm --build-arg TARGETOS=linux
+
 make helm.generate
 helm upgrade --install external-secrets ./deploy/charts/external-secrets/ --set image.repository=$IMAGE --set image.tag=$TAG
 ```

docs/guides-controller-class.md

@@ -0,0 +1,19 @@
+# Controller Classes
+
+> NOTE: this feature is experimental and not highly tested
+
+Controller classes are a proprierty set during the deployment that allows multiple controllers to work in a group of workloard. It works by separating which secretStores are going to be attributed to which controller. For the behavior of a single controller, no extra configuration is needed.
+
+## Setting up Controller Class
+
+In order to deploy the controller with a specific class, install the helm charts specifying the controller class, and create a `SecretStore` with the appropriate `spec.controller` values:
+```
+helm install custom-external-secrets external-secrets/external-secrets --set controllerClass=custom
+```
+``` yaml
+{% include 'controller-class-store.yaml' %}
+```
+
+Now, any `ExternalSecret` bound to this secret store will be evaluated by the operator with the controllerClass custom.
+
+> Note: Any SecretStore without `spec.controller` set will be considered as valid by any operator, regardless of their respective controllerClasses.

docs/provider-google-secrets-manager.md

@@ -38,24 +38,7 @@ metadata:
 You can reference this particular ServiceAccount in a `SecretStore` or `ClusterSecretStore`. It's important that you also set the `projectID`, `clusterLocation` and `clusterName`. The Namespace on the `serviceAccountRef` is ignored when using a `SecretStore` resource. This is needed to isolate the namespaces properly.
 
 ```yaml
-apiVersion: external-secrets.io/v1alpha1
-kind: ClusterSecretStore
-metadata:
-  name: gcp-wi
-spec:
-  provider:
-    gcpsm:
-      projectID: my-project
-      auth:
-        workloadIdentity:
-          # name of the cluster region
-          clusterLocation: europe-central2
-          # name of the GKE cluster
-          clusterName: example-workload-identity
-          # reference the sa from above
-          serviceAccountRef:
-            name: team-a
-            namespace: team-a
+{% include 'gcpsm-wi-secret-store.yaml' %}
 ```
 
 *You need to give the Google service account the `roles/iam.serviceAccountTokenCreator` role so it can generate a service account token for you (not necessary in the Pod-based Workload Identity bellow)*
@@ -90,14 +73,7 @@ The pod now has the identity. Now you need to configure the `SecretStore`.
 You just need to set the `projectID`, all other fields can be omitted.
 
 ```yaml
-apiVersion: external-secrets.io/v1alpha1
-kind: SecretStore
-metadata:
-  name: example
-spec:
-  provider:
-    gcpsm:
-      projectID: pid
+{% include 'gcpsm-pod-wi-secret-store.yaml' %}
 ```
 
 ### GCP Service Account authentication

docs/snippets/aws-parameter-store.yaml

@@ -3,7 +3,6 @@ kind: SecretStore
 metadata:
   name: secretstore-sample
 spec:
-  controller: dev
   provider:
     aws:
       service: ParameterStore

docs/snippets/aws-sm-store.yaml

@@ -3,7 +3,6 @@ kind: SecretStore
 metadata:
   name: secretstore-sample
 spec:
-  controller: dev
   provider:
     aws:
       service: SecretsManager

docs/snippets/azkv-external-secret.yaml

@@ -35,7 +35,3 @@ spec:
     remoteRef:
       key: key/dev-key-test
 
-  # dataFrom , return ALL secrets saved in the referenced secretStore
-  # each secret name in the KV will be used as the secret key in the SECRET k8s target object
-  dataFrom:
-  - name: "*"

docs/snippets/azkv-secret-store-mi.yaml

@@ -7,7 +7,7 @@ spec:
     # provider type: azure keyvault
     azurekv:
       authType: ManagedIdentity
-      # Optionally set the Id of the Managed Identity, if multiple identities is assignet to external-secrets operator
+      # Optionally set the Id of the Managed Identity, if multiple identities are assigned to external-secrets operator
       identityId: "<MI_clientId>"
       # URL of your vault instance, see: https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates
       vaultUrl: "https://my-keyvault-name.vault.azure.net"

docs/snippets/basic-secret-store.yaml

@@ -3,11 +3,9 @@ kind: SecretStore
 metadata:
   name: secretstore-sample
 spec:
-  controller: dev
   provider:
     aws:
       service: SecretsManager
-      role: arn:aws:iam::123456789012:role/team-a-reader
       region: us-east-1
       auth:
         secretRef:

docs/snippets/controller-class-store.yaml

@@ -0,0 +1,17 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: controller-custom-example
+spec:
+  #define the controller label to the matching value of the deployment
+  controller: custom
+  #configure provider the same way
+  provider:
+    vault:
+      server: "http://vault.default:8200"
+      path: "secret"
+      version: "v2"
+      auth:
+        kubernetes:
+          mountPath: "kubernetes"
+          role: "demo-role"

docs/snippets/gcpsm-pod-wi-secret-store.yaml

@@ -0,0 +1,8 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: example
+spec:
+  provider:
+    gcpsm:
+      projectID: pid

docs/snippets/gcpsm-wi-secret-store.yaml

@@ -0,0 +1,18 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: ClusterSecretStore
+metadata:
+  name: example
+spec:
+  provider:
+    gcpsm:
+      projectID: my-project
+      auth:
+        workloadIdentity:
+          # name of the cluster region
+          clusterLocation: europe-central2
+          # name of the GKE cluster
+          clusterName: example-workload-identity
+          # reference the sa from above
+          serviceAccountRef:
+            name: team-a
+            namespace: team-a

hack/api-docs/mkdocs.yml

@@ -31,6 +31,7 @@ nav:
     - Introduction: guides-introduction.md
     - Getting started: guides-getting-started.md
     - Advanced Templating: guides-templating.md
+    - Controller Classes: guides-controller-class.md
     - All keys, One secret: guides-all-keys-one-secret.md
     - Common K8S Secret Types: guides-common-k8s-secret-types.md
     - Multi Tenancy: guides-multi-tenancy.md