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

chore(docs): document es update behavior

Browse source
This commit is contained in:
Moritz Johner 2021-06-25 22:28:46 +02:00
parent 9d1d1869f8
commit fb726dfb17
9 changed files with 195 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

135
README.md
View file

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

3
apis/externalsecrets/v1alpha1/secretstore_types.go
View file

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

1
apis/externalsecrets/v1alpha1/zz_generated.deepcopy.go
View file

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

23
deploy/crds/external-secrets.io_clustersecretstores.yaml
View file

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

9
docs/api-clustersecretstore.md
View file

@ -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' %}
```

18
docs/api-externalsecret.md
View file

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

8
docs/api-overview.md
View file

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

100
docs/snippets/full-cluster-secret-store.yaml Normal file
View file

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

24
docs/spec.md
View file

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