github/kubernetes
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updates READMEs regarding the new behavior of addon-manager

Browse Source
This commit is contained in:
Zihong Zheng
2017-02-24 16:42:41 -08:00
parent c7189fd555
commit 72b35ce7d7
2 changed files with 49 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
cluster/addons/README.md
View File

@@ -1,53 +1,34 @@
# Cluster add-ons # Cluster add-ons
## Overview
Cluster add-ons are resources like Services and Deployments (with pods) that are Cluster add-ons are resources like Services and Deployments (with pods) that are
shipped with the Kubernetes binaries and are considered an inherent part of the shipped with the Kubernetes binaries and are considered an inherent part of the
Kubernetes clusters. The add-ons are visible through the API (they can be listed using Kubernetes clusters.
`kubectl`), but direct manipulation of these objects through Apiserver is discouraged
because the system will bring them back to the original state, in particular:
- If an add-on is deleted, it will be recreated automatically.
- If an add-on is updated through Apiserver, it will be reconfigured to the state given by
the supplied fields in the initial config.
On the cluster, the add-ons are kept in `/etc/kubernetes/addons` on the master node, in There are currently two classes of add-ons:
yaml / json files. The addon manager periodically `kubectl apply`s the contents of this - Add-ons that will be reconciled.
directory. Any legit modification would be reflected on the API objects accordingly. - Add-ons that will be created if they don't exist.
Particularly, rolling-update for deployments is now supported.
Each add-on must specify the following label: `kubernetes.io/cluster-service: true`. More details could be found in [addon-manager/README.md](addon-manager/README.md).
Config files that do not define this label will be ignored. For those resources
exist in `kube-system` namespace but not in `/etc/kubernetes/addons`, addon manager
will attempt to remove them if they are attached with this label. Currently the other
usage of `kubernetes.io/cluster-service` is for `kubectl cluster-info` command to recognize
these cluster services.
The suggested naming for most types of resources is just `<basename>` (with no version ## Cooperating Horizontal / Vertical Auto-Scaling with "reconcile class addons"
number) because we do not expect the resource name to change. But resources like `Pod`
, `ReplicationController` and `DaemonSet` are exceptional. As `Pod` updates may not change
fields other than `containers[*].image` or `spec.activeDeadlineSeconds` and may not add or
remove containers, it may not be sufficient during a major update. For `ReplicationController`,
most of the modifications would be legit, but the underlying pods would not got re-created
automatically. `DaemonSet` has similar problem as the `ReplicationController`. In these
cases, the suggested naming is `<basename>-<version>`. When version changes, the system will
delete the old one and create the new one (order not guaranteed).
# Add-on update procedure "Reconcile" class addons will be periodically reconciled to the original state given
by the initial config. In order to make Horizontal / Vertical Auto-scaling functional,
the related fields in config should be left unset. More specifically, leave `replicas`
in `ReplicationController` / `Deployment` / `ReplicaSet` unset for Horizontal Scaling,
leave `resources` for container unset for Vertical Scaling. The periodic reconcile
won't clobbered these fields, hence they could be managed by Horizontal / Vertical
Auto-scaler.
To update add-ons, just update the contents of `/etc/kubernetes/addons` ## Add-on naming
directory with the desired definition of add-ons. Then the system will take care
of:
- Removing objects from the API server whose manifest was removed. The suggested naming for most of the resources is `<basename>` (with no version number).
- Creating objects from new manifests Though resources like `Pod`, `ReplicationController` and `DaemonSet` are exceptional.
- Updating objects whose fields are legally changed. It would be hard to update `Pod` because many fields in `Pod` are immutable. For
`ReplicationController` and `DaemonSet`, in-place update may not trigger the underlying
# Cooperating with Horizontal / Vertical Auto-Scaling pods to be re-created. You probably need to change their names during update to trigger
a complete deletion and creation.
As all cluster add-ons will be reconciled to the original state given by the initial config.
In order to make Horizontal / Vertical Auto-scaling functional, the related fields in config should
be left unset. More specifically, leave `replicas` in `ReplicationController` / `Deployment`
/ `ReplicaSet` unset for Horizontal Scaling, and leave `resources` for container unset for Vertical
Scaling. The periodical update won't include these specs, which will be managed by Horizontal / Vertical
Auto-scaler.
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/cluster/addons/README.md?pixel)]() [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/cluster/addons/README.md?pixel)]()

34
cluster/addons/addon-manager/README.md
View File

@@ -1,15 +1,35 @@
### addon-manager ### Addon-manager
The `addon-manager` periodically `kubectl apply`s the Kubernetes manifest in the `/etc/kubernetes/addons` directory, addon-manager manages two classes of addons with given template files.
and handles any added / updated / deleted addon. - Addons with label `addonmanager.kubernetes.io/mode=Reconcile` will be periodically
reconciled. Direct manipulation to these addons through apiserver is discouraged because
addon-manager will bring them back to the original state. In particular:
- Addon will be re-created if it is deleted.
- Addon will be reconfigured to the state given by the supplied fields in the template
file periodically.
- Addon will be deleted when its manifest file is deleted.
- Addons with label `addonmanager.kubernetes.io/mode=EnsureExists` will be checked for
existence only. Users can edit these addons as they want. In particular:
- Addon will only be created/re-created with the given template file when there is no
instance of the resource with that name.
- Addon will not be deleted when the manifest file is deleted.
It supports all types of resource. Notes:
The requirement is to label them with `kubernetes.io/cluster-service: "true"`. - Label `kubernetes.io/cluster-service=true` is deprecated (only for Addon Manager).
In future release (after one year), Addon Manager may not respect it anymore. Addons
The `addon-manager` is built for multiple architectures. have this label but without `addonmanager.kubernetes.io/mode=EnsureExists` will be
treated as "reconcile class addons" for now.
- Resources under $ADDON_PATH (default `/etc/kubernetes/addons/`) needs to have either one
of these two labels. Meanwhile namespaced resources need to be in `kube-system` namespace.
Otherwise it will be omitted.
- The above label and namespace rule does not stand for `/opt/namespace.yaml` and
resources under `/etc/kubernetes/admission-controls/`. addon-manager will attempt to
create them regardless during startup.
#### How to release #### How to release
The `addon-manager` is built for multiple architectures.
1. Change something in the source 1. Change something in the source
2. Bump `VERSION` in the `Makefile` 2. Bump `VERSION` in the `Makefile`
3. Bump `KUBECTL_VERSION` in the `Makefile` if required 3. Bump `KUBECTL_VERSION` in the `Makefile` if required