diff --git a/docs/contributing-process.md b/docs/contributing-process.md index fb35b94bf..a5e378b2d 100644 --- a/docs/contributing-process.md +++ b/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. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..27872a7f9 --- /dev/null +++ b/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. + + + diff --git a/docs/pictures/diagrams-high-level-simple.png b/docs/pictures/diagrams-high-level-simple.png index 43a9e2b68..460003eb9 100644 Binary files a/docs/pictures/diagrams-high-level-simple.png and b/docs/pictures/diagrams-high-level-simple.png differ diff --git a/docs/provider-kubernetes.md b/docs/provider-kubernetes.md index 23bac751b..55e5bc394 100644 --- a/docs/provider-kubernetes.md +++ b/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) diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 000000000..ecb54f900 --- /dev/null +++ b/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 diff --git a/docs/stability-support.md b/docs/stability-support.md index 86994d966..b789150a2 100644 --- a/docs/stability-support.md +++ b/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.4.x | 1.16 → 1.23 | -| 0.3.x | 1.16 → 1.23 | +| 0.5.x | 1.19 → 1.24 | +| 0.4.x | 1.16 → 1.24 | +| 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) diff --git a/hack/api-docs/mkdocs.yml b/hack/api-docs/mkdocs.yml index 7b8cf9cac..b56828975 100644 --- a/hack/api-docs/mkdocs.yml +++ b/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