Skip to content

Commit

Permalink
Merge pull request #148 from fluxcd/docs/improve-kubeconfig-docs
Browse files Browse the repository at this point in the history 
Improve remote cluster documentation
  • Loading branch information
@stefanprodan
stefanprodan authored Oct 20, 2020
2 parents df3af29 + 154560f commit 198eda8
Show file tree
Hide file tree
Showing 4 changed files with 44 additions and 66 deletions.
24 changes: 9 additions & 15 deletions api/v1beta1/kustomization_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,22 +122,16 @@ type Decryption struct {
SecretRef *corev1.LocalObjectReference `json:"secretRef,omitempty"`
}

// KubeConfig references a Kubernetes secret generated by CAPI.
// that contains a kubeconfig file.
// KubeConfig references a Kubernetes secret that contains a kubeconfig file.
type KubeConfig struct {
// The secret name containing a 'value' key with the kubeconfig file as the value.
// This secret must be in the same Namespace as the Kustomization.
// KubeConfig secrets maintained by Cluster API bootstrap providers can be used here.
// (ex: If your CAPI Cluster's name is `stage`, set this to `stage-kubeconfig`.
// Ensure the Kustomization is in the same Namespace as the Cluster object.
// Ref: https://github.com/kubernetes-sigs/cluster-api/blob/release-0.3/util/secret/consts.go#L24)
// The reconciliation clients are regularly refreshed from the Secret, so
// rotating kubeconfigs for KaaS control-planes from cloud-providers are supported.
// These kubeconfigs follow the same design constraints as Cluster API.
// It is recommended that kubeconfigs be self-contained, and the Secret be
// regularly updated if credentials such as a cloud-access-token expire.
// Cloud-specific `cmd-path` auth helpers will not function without adding
// binaries and credentials to the kustomize-controller Pod.
// SecretRef holds the name to a secret that contains a 'value' key with
// the kubeconfig file as the value. It must be in the same namespace as
// the Kustomization.
// It is recommended that the kubeconfig is self-contained, and the secret
// is regularly updated if credentials such as a cloud-access-token expire.
// Cloud specific `cmd-path` auth helpers will not function without adding
// binaries and credentials to the Pod that is responsible for reconciling
// the Kustomization.
// +required
SecretRef corev1.LocalObjectReference `json:"secretRef,omitempty"`
}
Expand Down
23 changes: 8 additions & 15 deletions config/crd/bases/kustomize.toolkit.fluxcd.io_kustomizations.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,21 +118,14 @@ spec:
remote cluster.
properties:
secretRef:
description: 'The secret name containing a ''value'' key with
the kubeconfig file as the value. This secret must be in the
same Namespace as the Kustomization. KubeConfig secrets maintained
by Cluster API bootstrap providers can be used here. (ex: If
your CAPI Cluster''s name is `stage`, set this to `stage-kubeconfig`.
Ensure the Kustomization is in the same Namespace as the Cluster
object. Ref: https://github.com/kubernetes-sigs/cluster-api/blob/release-0.3/util/secret/consts.go#L24)
The reconciliation clients are regularly refreshed from the
Secret, so rotating kubeconfigs for KaaS control-planes from
cloud-providers are supported. These kubeconfigs follow the
same design constraints as Cluster API. It is recommended that
kubeconfigs be self-contained, and the Secret be regularly updated
if credentials such as a cloud-access-token expire. Cloud-specific
`cmd-path` auth helpers will not function without adding binaries
and credentials to the kustomize-controller Pod.'
description: SecretRef holds the name to a secret that contains
a 'value' key with the kubeconfig file as the value. It must
be in the same namespace as the Kustomization. It is recommended
that the kubeconfig is self-contained, and the secret is regularly
updated if credentials such as a cloud-access-token expire.
Cloud specific `cmd-path` auth helpers will not function without
adding binaries and credentials to the Pod that is responsible
for reconciling the Kustomization.
properties:
name:
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
Expand Down
24 changes: 9 additions & 15 deletions docs/api/kustomize.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -449,8 +449,7 @@ Kubernetes core/v1.LocalObjectReference
(<em>Appears on:</em>
<a href="#kustomize.toolkit.fluxcd.io/v1beta1.KustomizationSpec">KustomizationSpec</a>)
</p>
<p>KubeConfig references a Kubernetes secret generated by CAPI.
that contains a kubeconfig file.</p>
<p>KubeConfig references a Kubernetes secret that contains a kubeconfig file.</p>
<div class="md-typeset__scrollwrap">
<div class="md-typeset__table">
<table>
Expand All @@ -471,19 +470,14 @@ Kubernetes core/v1.LocalObjectReference
</em>
</td>
<td>
<p>The secret name containing a &lsquo;value&rsquo; key with the kubeconfig file as the value.
This secret must be in the same Namespace as the Kustomization.
KubeConfig secrets maintained by Cluster API bootstrap providers can be used here.
(ex: If your CAPI Cluster&rsquo;s name is <code>stage</code>, set this to <code>stage-kubeconfig</code>.
Ensure the Kustomization is in the same Namespace as the Cluster object.
Ref: <a href="https://github.com/kubernetes-sigs/cluster-api/blob/release-0.3/util/secret/consts.go#L24)">https://github.com/kubernetes-sigs/cluster-api/blob/release-0.3/util/secret/consts.go#L24)</a>
The reconciliation clients are regularly refreshed from the Secret, so
rotating kubeconfigs for KaaS control-planes from cloud-providers are supported.
These kubeconfigs follow the same design constraints as Cluster API.
It is recommended that kubeconfigs be self-contained, and the Secret be
regularly updated if credentials such as a cloud-access-token expire.
Cloud-specific <code>cmd-path</code> auth helpers will not function without adding
binaries and credentials to the kustomize-controller Pod.</p>
<p>SecretRef holds the name to a secret that contains a &lsquo;value&rsquo; key with
the kubeconfig file as the value. It must be in the same namespace as
the Kustomization.
It is recommended that the kubeconfig is self-contained, and the secret
is regularly updated if credentials such as a cloud-access-token expire.
Cloud specific <code>cmd-path</code> auth helpers will not function without adding
binaries and credentials to the Pod that is responsible for reconciling
the Kustomization.</p>
</td>
</tr>
</tbody>
Expand Down
39 changes: 18 additions & 21 deletions docs/spec/v1beta1/kustomization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,19 +93,14 @@ This can be used with Cluster API:

```go
type KubeConfig struct {
// The secret name containing a 'value' key with the kubeconfig file as the value.
// This secret must be in the same Namespace as the Kustomization.
// KubeConfig secrets maintained by Cluster API bootstrap providers can be used here.
// (ex: If your CAPI Cluster's name is `stage`, set this to `stage-kubeconfig`.
// Ensure the Kustomization is in the same Namespace as the Cluster object.
// Ref: https://github.com/kubernetes-sigs/cluster-api/blob/release-0.3/util/secret/consts.go#L24)
// The reconciliation clients are regularly refreshed from the Secret, so
// rotating kubeconfigs for KaaS control-planes from cloud-providers are supported.
// These kubeconfigs follow the same design constraints as Cluster API.
// It is recommended that kubeconfigs be self-contained, and the Secret be
// regularly updated if credentials such as a cloud-access-token expire.
// Cloud-specific `cmd-path` auth helpers will not function without adding
// binaries and credentials to the kustomize-controller Pod.
// SecretRef holds the name to a secret that contains a 'value' key with
// the kubeconfig file as the value. It must be in the same namespace as
// the Kustomization.
// It is recommended that the kubeconfig is self-contained, and the secret
// is regularly updated if credentials such as a cloud-access-token expire.
// Cloud specific `cmd-path` auth helpers will not function without adding
// binaries and credentials to the Pod that is responsible for reconciling
// the Kustomization.
// +required
SecretRef corev1.LocalObjectReference `json:"secretRef,omitempty"`
}
Expand Down Expand Up @@ -498,18 +493,19 @@ account. If the kustomization contains cluster level objects like CRDs or object
namespace, the reconciliation will fail since the account it runs under has no permissions to alter objects
outside of the `webapp` namespace.

## Cluster-API / Remote Clusters
## Remote Clusters / Cluster-API

If the `kubeConfig` field is set, objects will be applied, health-checked, pruned, and deleted for the default
cluster specified in that KubeConfig instead of using the in-cluster ServiceAccount.

This is done by specifying a KubeConfig from a Secret in the same Namespace as the Kustomization.
The KubeConfig bytes are loaded from the `value` key of the Secret's data.
This Secret can be regularly updated if cluster-access-tokens have to rotate due to expiration.
The secret defined in the `kubeConfig.SecretRef` must exist in the same namespace as the Kustomization.
On every reconciliation, the KubeConfig bytes will be loaded from the `values` key of the secret's data, and
the secret can thus be regularly updated if cluster-access-tokens have to rotate due to expiration.

This composes well with Cluster API bootstrap providers such as CAPBK(kubeadm) as well as the CAPA(aws) EKS integration.
This composes well with Cluster API bootstrap providers such as CAPBK (kubeadm) as well as the CAPA (AWS) EKS
integration.

To reconcile a kustomization to a CAPI controlled cluster, put the `Kustomization` in the same Namespace as your
To reconcile a Kustomization to a CAPI controlled cluster, put the `Kustomization` in the same namespace as your
`Cluster` object, and set the `kubeConfig.secretRef.name` to `<cluster-name>-kubeconfig`:

```yaml
Expand Down Expand Up @@ -560,8 +556,9 @@ spec:
The Cluster and Kustomization can be created at the same time.
The Kustomization will eventually reconcile once the cluster is available.

If you wish to target clusters created by other means than CAPI, you can create a ServiceAccount on the remote cluster,
generate a kube config for that account, then create a secret on the cluster where kustomize-controller is running e.g.:
If you wish to target clusters created by other means than CAPI, you can create a ServiceAccount
on the remote cluster, generate a KubeConfig for that account, and then create a secret on the
cluster where kustomize-controller is running e.g.:

```sh
kubectl create secret generic prod-kubeconfig \
Expand Down

0 comments on commit 198eda8

Please sign in to comment.