Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve remote cluster documentation #148

Merged
merged 1 commit into from
Oct 20, 2020
Merged

Improve remote cluster documentation #148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 9 additions & 15 deletions api/v1beta1/kustomization_types.go
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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