chore(docs): document es update behavior

README.md

@@ -17,130 +17,26 @@ Multiple people and organizations are joining efforts to create a single Externa
 - [Google Cloud Secrets Manager](https://external-secrets.io/provider-google-secrets-manager/)
 - [Azure Key Vault](https://external-secrets.io/provider-azure-key-vault/)
 
-## ESO installation with an AWS example
-
-
-If you want to use Helm:
-
-```shell
-helm repo add external-secrets https://charts.external-secrets.io
-
-helm install external-secrets \
-   external-secrets/external-secrets \
-    -n external-secrets \
-    --create-namespace \
-  # --set installCRDs=true
-```
-
-If you want to run it locally against the active Kubernetes cluster context:
-
-```shell
-git clone https://github.com/external-secrets/external-secrets.git
-make crds.install
-make run
-```
-
-Create a secret containing your AWS credentials:
-
-```shell
-echo -n 'KEYID' > ./access-key
-echo -n 'SECRETKEY' > ./secret-access-key
-kubectl create secret generic awssm-secret --from-file=./access-key  --from-file=./secret-access-key
-```
-
-Create a secret inside AWS Secret Manager with name `my-json-secret` with the following data:
-
-```json
-{
-  "name": {"first": "Tom", "last": "Anderson"},
-  "friends": [
-    {"first": "Dale", "last": "Murphy"},
-    {"first": "Roger", "last": "Craig"},
-    {"first": "Jane", "last": "Murphy"}
-  ]
-}
-```
-
-Apply the sample resources (omitting role and controller keys here, you should not omit them in production):
-
-```yaml
-# secretstore.yaml
-apiVersion: external-secrets.io/v1alpha1
-kind: SecretStore
-metadata:
-  name: secretstore-sample
-spec:
-  provider:
-    aws:
-      service: SecretsManager
-      region: us-east-2
-      auth:
-        secretRef:
-          accessKeyIDSecretRef:
-            name: awssm-secret
-            key: access-key
-          secretAccessKeySecretRef:
-            name: awssm-secret
-            key: secret-access-key
-```
-
-```yaml
-# externalsecret.yaml
-apiVersion: external-secrets.io/v1alpha1
-kind: ExternalSecret
-metadata:
-  name: example
-spec:
-  refreshInterval: 1m
-  secretStoreRef:
-    name: secretstore-sample
-    kind: SecretStore
-  target:
-    name: secret-to-be-created
-    creationPolicy: Owner
-  data:
-  - secretKey: firstname
-    remoteRef:
-      key: my-json-secret
-      property: name.first # Tom
-  - secretKey: first_friend
-    remoteRef:
-      key: my-json-secret
-      property: friends.1.first # Roger
-```
-
-```shell
-kubectl apply -f secretstore.yaml
-kubectl apply -f externalsecret.yaml
-```
-
-Running `kubectl get secret secret-to-be-created` should return a new secret created by the operator.
-
-You can get one of its values with jsonpath (This should return `Roger`):
-
-```shell
-kubectl get secret secret-to-be-created   -o jsonpath='{.data.first_friend}' | base64 -d
-```
-
-We will add more documentation once we have the implementation for the different providers. You can find some here: https://external-secrets.io
-
 ## Stability and Support Level
 
 ### Internally maintained:
 
-| Provider        | Stability     |                   Contact                      | 
-| --------------- |:-------------:|-----------------------------------------------:|
-| AWS SM          |     alpha     | [ESO Org](https://github.com/external-secrets) |
-| AWS PS          |     alpha     | [ESO Org](https://github.com/external-secrets) |
-| Hashicorp Vault |     alpha     | [ESO Org](https://github.com/external-secrets) |
-| GCP SM          |     alpha     | [ESO Org](https://github.com/external-secrets) |
-
+| Provider                                                                 | Stability |                                        Contact |
+| ------------------------------------------------------------------------ | :-------: | ---------------------------------------------: |
+| [AWS SM](https://external-secrets.io/provider-aws-secrets-manager/)      |   alpha   | [ESO Org](https://github.com/external-secrets) |
+| [AWS PS](https://external-secrets.io/provider-aws-parameter-store/)      |   alpha   | [ESO Org](https://github.com/external-secrets) |
+| [Hashicorp Vault](https://external-secrets.io/provider-hashicorp-vault/) |   alpha   | [ESO Org](https://github.com/external-secrets) |
+| [GCP SM](https://external-secrets.io/provider-google-secrets-manager/)   |   alpha   | [ESO Org](https://github.com/external-secrets) |
 
 ### Community maintained:
 
-| Provider        | Stability     |                   Contact                  | 
-| --------------- |:-------------:|:------------------------------------------:|
-| Azure KV        |     alpha     | @ahmedmus-1A @asnowfix @ncourbet-1A @1A-mj |
+| Provider                                                          | Stability |                  Contact                   |
+| ----------------------------------------------------------------- | :-------: | :----------------------------------------: |
+| [Azure KV](https://external-secrets.io/provider-azure-key-vault/) |   alpha   | @ahmedmus-1A @asnowfix @ncourbet-1A @1A-mj |
+
+## Documentation
+
+External Secrets Operator guides and reference documentation is available at [external-secrets.io](external-secrets.io).
 
 ## Support
 
@@ -148,11 +44,14 @@ You can use GitHub's [issues](https://github.com/external-secrets/external-secre
 
 Even though we have active maintainers and people assigned to this project, we kindly ask for patience when asking for support. We will try to get to priority issues as fast as possible, but there may be some delays.
 
-
 ## Contributing
 
 We welcome and encourage contributions to this project! Please read the [Developer](https://www.external-secrets.io/contributing-devguide/) and [Contribution process](https://www.external-secrets.io/contributing-process/) guides. Also make sure to check the [Code of Conduct](https://www.external-secrets.io/contributing-coc/) and adhere to its guidelines.
 
+## Security
+
+Please report vulnerabilities by email to [external-secrets contact](contact@external-secrets.io), also see our [security policy](SECURITY.md) for details.
+
 ## Kicked off by
 
 ![](assets/CS_logo_1.png)

apis/externalsecrets/v1alpha1/secretstore_types.go

@@ -110,7 +110,8 @@ type ClusterSecretStore struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec SecretStoreSpec `json:"spec,omitempty"`
+	Spec   SecretStoreSpec   `json:"spec,omitempty"`
+	Status SecretStoreStatus `json:"status,omitempty"`
 }
 
 // +kubebuilder:object:root=true

apis/externalsecrets/v1alpha1/zz_generated.deepcopy.go

@@ -138,6 +138,7 @@ func (in *ClusterSecretStore) DeepCopyInto(out *ClusterSecretStore) {
 	out.TypeMeta = in.TypeMeta
 	in.ObjectMeta.DeepCopyInto(&out.ObjectMeta)
 	in.Spec.DeepCopyInto(&out.Spec)
+	in.Status.DeepCopyInto(&out.Status)
 }
 
 // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ClusterSecretStore.

deploy/crds/external-secrets.io_clustersecretstores.yaml

@@ -498,6 +498,29 @@ spec:
             required:
             - provider
             type: object
+          status:
+            description: SecretStoreStatus defines the observed state of the SecretStore.
+            properties:
+              conditions:
+                items:
+                  properties:
+                    lastTransitionTime:
+                      format: date-time
+                      type: string
+                    message:
+                      type: string
+                    reason:
+                      type: string
+                    status:
+                      type: string
+                    type:
+                      type: string
+                  required:
+                  - status
+                  - type
+                  type: object
+                type: array
+            type: object
         type: object
     served: true
     storage: true

docs/api-clustersecretstore.md

@@ -1,5 +1,8 @@
 ![ClusterSecretStore](./pictures/diagrams-high-level-cluster-detail.png)
 
-The `ClusterSecretStore` is a cluster scoped SecretStore that can be used by all
-`ExternalSecrets` from all namespaces unless you pin down its usage by using
-RBAC or Admission Control.
+The `ClusterSecretStore` is a cluster scoped SecretStore that can be referenced by all
+`ExternalSecrets` from all namespaces. Use it to offer a central gateway to your secret backend.
+
+``` yaml
+{% include 'full-secret-store.yaml' %}
+```

docs/api-externalsecret.md

@@ -7,6 +7,24 @@ be transformed and saved as a `Kind=Secret`:
 * you can specify how the secret should look like by specifying a
   `spec.target.template`
 
+## Template
+
+When the controller reconciles the `ExternalSecret` it will use the `spec.template` as a blueprint to construct a new `Kind=Secret`. You can use golang templates to define the blueprint and use template functions to transform secret values. See [advanced templating](guides-templating.md) for details.
+
+## Update Behavior
+
+The `Kind=Secret` is updated when:
+
+* the `spec.refreshInterval` has passed and is not `0`
+* the `ExternalSecret`'s `labels` or `annotations` are changed
+* the `ExternalSecret`'s `spec` has been changed
+
+You can trigger a secret refresh by using kubectl or any other kubernetes api client:
+
+```
+kubectl annotate es my-es force-sync=$(date +%s) --overwrite
+```
+
 ## Example
 
 Take a look at an annotated example to understand the design behind the

docs/api-overview.md

@@ -25,7 +25,7 @@ to.
 
 ### SecretStore
 
-The idea behind the `SecretStore` resource is to separate concerns of
+The idea behind the [SecretStore](api-secretstore.md) resource is to separate concerns of
 authentication/access and the actual Secret and configuration needed for
 workloads. The ExternalSecret specifies what to fetch, the SecretStore specifies
 how to access. This resource is namespaced.
@@ -37,7 +37,7 @@ The `SecretStore` contains references to secrets which hold credentials to
 access the external API.
 
 ### ExternalSecret
-An ExternalSecret declares what data to fetch. It has a reference to a
+An [ExternalSecret](api-externalsecret.md) declares what data to fetch. It has a reference to a
 `SecretStore` which knows how to access that data. The controller uses that
 `ExternalSecret` as a blueprint to create secrets.
 
@@ -47,8 +47,8 @@ An ExternalSecret declares what data to fetch. It has a reference to a
 
 ### ClusterSecretStore
 
-The `ClusterSecretStore` is just a global, cluster-wide SecretStore that can be
-referenced from all namespaces.
+The [ClusterSecretStore](api-clustersecretstore.md) is a global, cluster-wide SecretStore that can be
+referenced from all namespaces. You can use it to provide a central gateway to your secret provider.
 
 ## Behavior
 

docs/snippets/full-cluster-secret-store.yaml

@@ -0,0 +1,100 @@
+apiVersion: external-secrets.io/v1alpha1
+kind: ClusterSecretStore
+metadata:
+  name: example
+spec:
+
+  # Used to select the correct ESO controller (think: ingress.ingressClassName)
+  # The ESO controller is instantiated with a specific controller name
+  # and filters ES based on this property
+  # Optional
+  controller: dev
+
+  # provider field contains the configuration to access the provider
+  # which contains the secret exactly one provider must be configured.
+  provider:
+
+    # (1): AWS Secrets Manager
+    # aws configures this store to sync secrets using AWS Secret Manager provider
+    aws:
+      service: SecretsManager
+      # Role is a Role ARN which the SecretManager provider will assume
+      role: iam-role
+      # AWS Region to be used for the provider
+      region: eu-central-1
+      # Auth defines the information necessary to authenticate against AWS by
+      # getting the accessKeyID and secretAccessKey from an already created Kubernetes Secret
+      auth:
+        secretRef:
+          accessKeyID:
+            name: awssm-secret
+            key: access-key
+          secretAccessKey:
+            name: awssm-secret
+            key: secret-access-key
+
+    vault:
+      server: "https://vault.acme.org"
+      # Path is the mount path of the Vault KV backend endpoint
+      path: "secret"
+      # Version is the Vault KV secret engine version.
+      # This can be either "v1" or "v2", defaults to "v2"
+      version: "v2"
+      # vault enterprise namespace: https://www.vaultproject.io/docs/enterprise/namespaces
+      namespace: "a-team"
+      caBundle: "..."
+      auth:
+        # static token: https://www.vaultproject.io/docs/auth/token
+        tokenSecretRef:
+          name: "my-secret"
+          namespace: "secret-admin"
+          key: "vault-token"
+
+        # AppRole auth: https://www.vaultproject.io/docs/auth/approle
+        appRole:
+          path: "approle"
+          roleId: "db02de05-fa39-4855-059b-67221c5c2f63"
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault-token"
+
+        # Kubernetes auth: https://www.vaultproject.io/docs/auth/kubernetes
+        kubernetes:
+          mountPath: "kubernetes"
+          role: "demo"
+          # Optional service account reference
+          serviceAccountRef:
+            name: "my-sa"
+            namespace: "secret-admin"
+          # Optional secret field containing a Kubernetes ServiceAccount JWT
+          # used for authenticating with Vault
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault"
+
+    # (2): GCP Secret Manager
+    gcpsm:
+      # Auth defines the information necessary to authenticate against GCP by getting
+      # the credentials from an already created Kubernetes Secret.
+      auth:
+        secretRef:
+          secretAccessKeySecretRef:
+            name: gcpsm-secret
+            key: secret-access-credentials
+      projectID: myproject
+    # (TODO): add more provider examples here
+
+status:
+  # Standard condition schema
+  conditions:
+  # SecretStore ready condition indicates the given store is in ready
+  # state and able to referenced by ExternalSecrets
+  # If the `status` of this condition is `False`, ExternalSecret controllers
+  # should prevent attempts to fetch secrets
+  - type: Ready
+    status: "False"
+    reason: "ConfigError"
+    message: "SecretStore validation failed"
+    lastTransitionTime: "2019-08-12T12:33:02Z"

docs/spec.md

@@ -344,6 +344,18 @@ SecretStoreProvider
 </table>
 </td>
 </tr>
+<tr>
+<td>
+<code>status</code></br>
+<em>
+<a href="#external-secrets.io/v1alpha1.SecretStoreStatus">
+SecretStoreStatus
+</a>
+</em>
+</td>
+<td>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1alpha1.ExternalSecret">ExternalSecret
@@ -732,6 +744,17 @@ the target secret updated</p>
 </tr>
 <tr>
 <td>
+<code>syncedResourceVersion</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>SyncedResourceVersion keeps track of the last synced version</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>conditions</code></br>
 <em>
 <a href="#external-secrets.io/v1alpha1.ExternalSecretStatusCondition">
@@ -1362,6 +1385,7 @@ SecretStoreProvider
 </h3>
 <p>
 (<em>Appears on:</em>
+<a href="#external-secrets.io/v1alpha1.ClusterSecretStore">ClusterSecretStore</a>, 
 <a href="#external-secrets.io/v1alpha1.SecretStore">SecretStore</a>)
 </p>
 <p>