docs: add project roadmap to docs (#1166)

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

docs/contributing-process.md

@@ -2,6 +2,7 @@
 The Code, our TODOs and Documentation is maintained on
 [GitHub](https://github.com/external-secrets/external-secrets). All Issues
 should be opened in that repository.
+We have a [Roadmap](roadmap.md) to track progress for our road towards GA.
 
 ## Issues
 
@@ -111,6 +112,7 @@ make test.e2e.managed GINKGO_LABELS='gcp'
 Before we introduce significant changes to the project we want to gather feedback
 from the community to ensure that we progress in the right direction before we
 develop and release big changes. Significant changes include for example:
+
 * creating new custom resources
 * proposing breaking changes
 * changing the behavior of the controller significantly
@@ -122,7 +124,11 @@ and fill in your proposal. Open a pull request in draft mode and request feedbac
 
 We have a [GitHub Project Board](https://github.com/orgs/external-secrets/projects/2/views/1) where we organize issues on a high level. We group issues by milestone. Once all issues of a given milestone are closed we should prepare a new feature release. Issues of the next milestone have priority over other issues - but that does not mean that no one is allowed to start working on them.
 
-Issues must be _manually_ added to that board (at least for now, see [GH Roadmap](https://github.com/github/roadmap/issues/286)). Milestones must be assigned manually as well. If no milestone is assigned it is basically a backlog item. It is the responsibility of the maintainers to (1) assign new issues to the GH Project, (2) add a milestone if needed and (3) add appropriate labels.
+Issues must be _manually_ added to that board (at least for now, see [GH Roadmap](https://github.com/github/roadmap/issues/286)). Milestones must be assigned manually as well. If no milestone is assigned it is basically a backlog item. It is the responsibility of the maintainers to:
+
+1. assign new issues to the GH Project
+2. add a milestone if needed
+3. add appropriate labels
 
 If you would like to raise the priority of an issue for whatever reason feel free to comment on the issue or ping a maintainer.
 
@@ -136,6 +142,7 @@ We have three different channels through which support questions arise:
 3. GitHub Issues
 
 We use labels to identify GitHub Issues. Specifically for managing support cases we use the following labels to identify the state a support case is in:
+
 * `triage/needs-information`: Indicates an issue needs more information in order to work on it.
 * `triage/not-reproducible`: Indicates an issue can not be reproduced as described.
 * `triage/support`: Indicates an issue that is a support question.

docs/faq.md

@@ -0,0 +1,82 @@
+## Can i manually trigger a secret refresh?
+
+You can trigger a secret refresh by using kubectl or any other kubernetes api client.
+You just need to change an annotation, label or the spec of the resource:
+
+```
+kubectl annotate es my-es force-sync=$(date +%s) --overwrite
+```
+
+## How do i know when my secret was last synced?
+
+Every ExternalSecret resource contains a status condition that indicates the time when the secret was last synced:
+
+```
+kubectl get es my-external-secret -o yaml | grep condition -A 5
+  conditions:
+  - lastTransitionTime: "2022-05-21T21:02:47Z"
+    message: Secret was synced
+    reason: SecretSynced
+    status: "True"
+    type: Ready
+```
+
+## Differences to csi-secret-store
+Please take a look at this [issue comment here](https://github.com/external-secrets/external-secrets/issues/478#issuecomment-964413129).
+
+## How do i debug an external-secret that doesn't sync?
+
+First, check the status of the ExternalSecret resource using `kubectl describe`. That displays the status conditions as well as recent events.
+You should expect a status condition with `Type=Ready`, `Status=True`. Further you shouldn't see any events with `Type=Warning`. Read carefully if they exist.
+
+```
+kubectl describe es my-external-secret
+[...]
+Status:
+  Conditions:
+    Last Transition Time:   2022-05-21T21:02:47Z
+    Message:                Secret was synced
+    Reason:                 SecretSynced
+    Status:                 True
+    Type:                   Ready
+  Refresh Time:             2022-05-21T21:06:47Z
+  Synced Resource Version:  1-5c833527afd7ba3f426cb0082ee7e083
+Events:
+  Type     Reason        Age                  From              Message
+  ----     ------        ----                 ----              -------
+  Warning  UpdateFailed  4m12s                external-secrets  secrets "yyyyyyy" already exists
+  Normal   Updated       12s (x4 over 3m12s)  external-secrets  Updated Secret
+```
+
+If everything looks good you should check the corresponding secret store resource that is referenced from an ExternalSecret. Again, use `kubectl describe` to show status conditions and events and look for warning signs as described above.
+
+In an ideally, the store should be validated and Ready.
+
+```
+kubectl describe css kubernetes
+[...]
+Status:
+  Conditions:
+    Last Transition Time:  2022-05-21T21:02:47Z
+    Message:               store validated
+    Reason:                Valid
+    Status:                True
+    Type:                  Ready
+Events:
+  Type    Reason  Age                From                  Message
+  ----    ------  ----               ----                  -------
+  Normal  Valid   52s (x4 over 10m)  cluster-secret-store  store validated
+  Normal  Valid   52s (x4 over 10m)  cluster-secret-store  store validated
+```
+
+If everything looks normal so far, please go ahead and ensure that the created secret has the expected value. Also, take a look at the logs of the controller.
+
+## Upgrading from KES to ESO
+
+Migrating from KES to ESO is quite tricky! There is a tool we built to help users out available [here](https://github.com/external-secrets/kes-to-eso), and there is a small migration procedure.
+
+There are some incompatibilities between KES to ESO, and while the tool tries to cover most of them, some of them will require manual intervention. We recommend to first convert the manifest files, and actually see if the tool provides a warning about any file needed to be changed.
+Beware that the tool points the SecretStores to use KES Service Account, so you'll also need to tweak that if you plan to uninstall KES after the upgrade.
+
+
+

docs/provider-kubernetes.md

@@ -12,7 +12,7 @@ It's possible to authenticate against the Kubernetes API using client certificat
 
 1. Create a K8s Secret with a client token for the default service account
 
-```
+```yaml
 apiVersion: v1
 kind: Secret
 metadata:
@@ -27,7 +27,7 @@ The Servers `url` won't be present as it will default to `kubernetes.default`, a
 
 The `auth` section indicates that the type `token` will be used for authentication, it includes the path to fetch the token. Set `remoteNamespace` to the name of the namespace where your target secrets reside.
 
-```
+```yaml
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
@@ -47,26 +47,25 @@ spec:
             key: token
       remoteNamespace: default
 ```
-3. Create the local secret that will be synced 
+3. Create the local secret that will be synced
-              
+
-```
+```yaml
----
 apiVersion: v1
 kind: Secret
 metadata:
   name: secret-example
 data:
   extra: YmFyCg==
-```     
+```
 4. Finally create the ExternalSecret resource
 
-```
+```yaml
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
   name: example
 spec:
-  refreshInterval: 1h           
+  refreshInterval: 1h
   secretStoreRef:
     kind: SecretStore
     name: example               # name of the SecretStore (or kind specified)
@@ -83,8 +82,8 @@ spec:
 ### Remote Secret using a Token
 
 1. Create a K8s Secret with the encoded base64 ca and client token.
-   
+
-```
+```yaml
 apiVersion: v1
 kind: Secret
 metadata:
@@ -98,11 +97,11 @@ stringData:
 ```
 2. Create a SecretStore
 
-The Server section specifies the `url` of the remote Kubernetes API. In this example the Certificate Authority is fetch using the encoded base64 `caBundle`. 
+The Server section specifies the `url` of the remote Kubernetes API. In this example the Certificate Authority is fetch using the encoded base64 `caBundle`.
 
 The `auth` section indicates that the  `token` type will be used for authentication, it includes the path to fetch the token.
 
-```
+```yaml
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
@@ -122,16 +121,16 @@ spec:
           bearerToken:
             name: cluster-secrets
             key: bearerToken
-```     
+```
 4. Finally create the ExternalSecret resource
 
-```
+```yaml
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
   name: example
 spec:
-  refreshInterval: 1h           
+  refreshInterval: 1h
   secretStoreRef:
     kind: SecretStore
     name: example               # name of the SecretStore (or kind specified)

docs/roadmap.md

@@ -0,0 +1,31 @@
+# The road to external-secrets GA
+
+The following external-secret custom resource APIs are considered stable:
+
+* `ExternalSecret`
+* `ClusterExternalSecret`
+* `SecretStore`
+* `ClusterSecretStore`
+
+These CRDs are currently at `v1beta1` and are considered production ready. Going forward, breaking changes to these APIs will be accompanied by a conversion mechanism.
+
+We have identified the following areas of work. This is subject to change while we gather feedback. We have a [GitHub Project Board](https://github.com/orgs/external-secrets/projects/2/views/1) where we organize issues and milestones on a high level.
+
+* Conformance testing
+    * end to end testing with ArgoCD and Flux
+    * end to end testing for all project maintained providers
+* API enhancements
+    * consolidate provider fields
+    * dataFrom key rewrites
+    * provider versioning strategy
+    * pushing secrets to a provider
+* Documentation Improvements
+    * Troubleshooting Guides
+    * FAQ
+    * review multi tenancy docs
+    * provide security model for infosec teams
+    * provider specific guides
+* Observability
+    * Provide Grafana Dashboard and Prometheus alerts
+    * add provider-level metrics
+* Pentest & SBOM

docs/stability-support.md

@@ -6,9 +6,9 @@ We are currently in beta and support **only the latest release** for the time be
 
 | ESO Version | Kubernetes Version |
 | ----------- | ------------------ |
-| 0.5.x       | 1.19 → 1.23        |
+| 0.5.x       | 1.19 → 1.24        |
-| 0.4.x       | 1.16 → 1.23        |
+| 0.4.x       | 1.16 → 1.24        |
-| 0.3.x       | 1.16 → 1.23        |
+| 0.3.x       | 1.16 → 1.24        |
 
 ## Provider Stability and Support Level
 
@@ -20,7 +20,8 @@ The following table describes the stability level of each provider and who's res
 | [AWS Parameter Store](https://external-secrets.io/latest/provider-aws-parameter-store/)                    |  stable   |                                                                                                                   [external-secrets](https://github.com/external-secrets) |
 | [Hashicorp Vault](https://external-secrets.io/latest/provider-hashicorp-vault/)                            |  stable   |                                                                                                                   [external-secrets](https://github.com/external-secrets) |
 | [GCP Secret Manager](https://external-secrets.io/latest/provider-google-secrets-manager/)                  |  stable   |                                                                                                                   [external-secrets](https://github.com/external-secrets) |
-| [Azure Keyvault](https://external-secrets.io/latest/provider-azure-key-vault/)                             |   beta    | [@ahmedmus-1A](https://github.com/ahmedmus-1A) [@asnowfix](https://github.com/asnowfix) [@ncourbet-1A](https://github.com/ncourbet-1A) [@1A-mj](https://github.com/1A-mj) |
+| [Azure Keyvault](https://external-secrets.io/latest/provider-azure-key-vault/)                             |   stable    | [external-secrets](https://github.com/external-secrets) |
+| [Kubernetes](https://external-secrets.io/latest/provider-kubernetes) |   alpha   |                                                                                                                                      [external-secrets](https://github.com/external-secrets) |
 | [IBM Secrets Manager](https://external-secrets.io/latest/provider-ibm-secrets-manager/)                    |   alpha   |                            [@knelasevero](https://github.com/knelasevero) [@sebagomez](https://github.com/sebagomez) [@ricardoptcosta](https://github.com/ricardoptcosta) |
 | [Yandex Lockbox](https://external-secrets.io/latest/provider-yandex-lockbox/)                              |   alpha   |                                                                       [@AndreyZamyslov](https://github.com/AndreyZamyslov) [@knelasevero](https://github.com/knelasevero) |
 | [Gitlab Project Variables](https://external-secrets.io/latest/provider-gitlab-project-variables/)          |   alpha   |                                                                                                                                    [@Jabray5](https://github.com/Jabray5) |
@@ -30,14 +31,14 @@ The following table describes the stability level of each provider and who's res
 | [1Password](https://external-secrets.io/latest/provider-1password-automation)                              |   alpha   |                                                                         [@SimSpaceCorp](https://github.com/Simspace) [@snarlysodboxer](https://github.com/snarlysodboxer) |
 | [Generic Webhook](https://external-secrets.io/latest/provider-webhook)                                     |   alpha   |                                                                                                                                    [@willemm](https://github.com/willemm) |
 | [senhasegura DevOps Secrets Management (DSM)](https://external-secrets.io/latest/provider-senhasegura-dsm) |   alpha   |                                                                                                                                      [@lfraga](https://github.com/lfraga) |
-| [Kubernetes](https://external-secrets.io/latest/provider-kubernetes) |   alpha   |                                                                                                                                      [@rodrmartinez](https://github.com/rodrmartinez) |
 
 ## Support Policy
 
-We provide technical support and provide security & bug fixes for the above listed versions.
+We provide technical support and security / bug fixes for the above listed versions.
 
 ### Technical support
 We provide assistance for deploying/upgrading etc. on a best-effort basis. You can request support through the following channels:
+
 * [Kubernetes Slack
   #external-secrets](https://kubernetes.slack.com/messages/external-secrets)
 * GitHub [Issues](https://github.com/external-secrets/external-secrets/issues)

hack/api-docs/mkdocs.yml

@@ -88,5 +88,7 @@ nav:
     - Contributing Process: contributing-process.md
     - Release Process: contributing-release.md
     - Code of Conduct: contributing-coc.md
+  - Roadmap: roadmap.md
+  - FAQ: faq.md
   - Stability and Support: stability-support.md
   - Deprecation Policy: deprecation-policy.md