mirrors/external-secrets
1
0
Fork 0
mirror of https://github.com/external-secrets/external-secrets.git synced 2024-12-14 11:57:59 +00:00
Code Activity

docs: add project roadmap to docs (#1166)

Browse source 
Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>
This commit is contained in:
Moritz Johner 2022-05-23 11:18:18 +02:00 committed by GitHub
parent 64969f01c1
commit 7a40151dfe
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 145 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/contributing-process.md
View file

@ -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.

82
docs/faq.md Normal file
View file

@ -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.

BIN
docs/pictures/diagrams-high-level-simple.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 63 KiB

After

Width:  |  Height:  |  Size: 41 KiB

31
docs/provider-kubernetes.md
View file

@ -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)

31
docs/roadmap.md Normal file
View file

@ -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

13
docs/stability-support.md
View file

@ -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)

2
hack/api-docs/mkdocs.yml
View file

@ -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