From 6a2ea94b39674645f6672c94be190f25cc9f8cd2 Mon Sep 17 00:00:00 2001 From: Cristian Calin <6627509+cristicalin@users.noreply.github.com> Date: Tue, 1 Jun 2021 17:30:27 +0300 Subject: [PATCH] Docs improvements (#7660) * Docs: update sidebar * Docs: move registry documentation into docs/ * Docs: move rbd_provisioner documentation into docs/ * Docs: move cephfs_provisioner into docs/ * Docs: move local_volume_provisioner documentation into docs/ * Docs: move ambassador.md to docs/ingress_controller/ * Docs: move metallb.md to docs/ingress_controller/ * Docs: move ingress_nginx documentation into docs/ * Docs: move alb_ingress_controller documentation into docs/ * Docs: merge ambassador documentation into docs/ingress_controller/ * Docs: move cert_manager documentation into docs/ * Docs: move bootstrap-os documentation into docs/ * Docs: update file locations in sidebar --- docs/_sidebar.md | 19 ++++++++- .../README.md => docs/bootstrap-os.md | 0 .../README.md => docs/cert_manager.md | 0 .../alb_ingress_controller.md | 0 docs/{ => ingress_controller}/ambassador.md | 10 +++++ .../ingress_controller/ingress_nginx.md | 0 docs/{ => ingress_controller}/metallb.md | 0 .../kubernetes-apps/cephfs_provisioner.md | 15 +++---- .../local_volume_provisioner.md | 12 ++---- .../kubernetes-apps/rbd_provisioner.md | 0 .../kubernetes-apps/registry.md | 40 +++++------------- .../ingress_controller/ambassador/README.md | 41 ------------------- 12 files changed, 46 insertions(+), 91 deletions(-) rename roles/bootstrap-os/README.md => docs/bootstrap-os.md (100%) rename roles/kubernetes-apps/ingress_controller/cert_manager/README.md => docs/cert_manager.md (100%) rename roles/kubernetes-apps/ingress_controller/alb_ingress_controller/README.md => docs/ingress_controller/alb_ingress_controller.md (100%) rename docs/{ => ingress_controller}/ambassador.md (81%) rename roles/kubernetes-apps/ingress_controller/ingress_nginx/README.md => docs/ingress_controller/ingress_nginx.md (100%) rename docs/{ => ingress_controller}/metallb.md (100%) rename roles/kubernetes-apps/external_provisioner/cephfs_provisioner/README.md => docs/kubernetes-apps/cephfs_provisioner.md (90%) rename roles/kubernetes-apps/external_provisioner/local_volume_provisioner/README.md => docs/kubernetes-apps/local_volume_provisioner.md (94%) rename roles/kubernetes-apps/external_provisioner/rbd_provisioner/README.md => docs/kubernetes-apps/rbd_provisioner.md (100%) rename roles/kubernetes-apps/registry/README.md => docs/kubernetes-apps/registry.md (91%) delete mode 100644 roles/kubernetes-apps/ingress_controller/ambassador/README.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 17e22619c..e07deab4e 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -14,30 +14,45 @@ * [Calico](docs/calico.md) * [Flannel](docs/flannel.md) * [Kube Router](docs/kube-router.md) + * [Kube OVN](docs/kube-ovn.md) * [Weave](docs/weave.md) * [Multus](docs/multus.md) + * [OVN4NFV](docs/ovn4nfv.md) * Ingress - * [Ambassador](docs/ambassador.md) + * [ALB Ingress](docs/ingress_controller/alb_ingress_controller.md) + * [Ambassador](docs/ingress_controller/ambassador.md) + * [MetalLB](docs/ingress_controller/metallb.md) + * [Nginx Ingress](docs/ingress_controller/ingress_nginx.md) * [Cloud providers](docs/cloud.md) * [AWS](docs/aws.md) * [Azure](docs/azure.md) * [OpenStack](/docs/openstack.md) * [Equinix Metal](/docs/equinix-metal.md) * [vSphere](/docs/vsphere.md) -* Operating Systems +* [Operating Systems](docs/bootstrap-os.md) * [Debian](docs/debian.md) * [Flatcar Container Linux](docs/flatcar.md) * [Fedora CoreOS](docs/fcos.md) * [OpenSUSE](docs/opensuse.md) + * [RedHat Enterprise Linux](docs/rhel.md) + * [CentOS/OracleLinux/AlmaLinux](docs/centos8.md) + * [Amaxon Linux 2](docs/amazonlinux.md) * CRI * [Containerd](docs/containerd.md) * [CRI-O](docs/cri-o.md) + * [Kata Containers](docs/kata-containers.md) * Advanced * [Proxy](/docs/proxy.md) * [Downloads](docs/downloads.md) * [Netcheck](docs/netcheck.md) + * [Cert Manager](docs/cert_manager.md) * [DNS Stack](docs/dns-stack.md) * [Kubernetes reliability](docs/kubernetes-reliability.md) + * [Local Registry](docs/kubernetes-apps/registry.md) +* External Storage Provisioners + * [RBD Provisioner](docs/kubernetes-apps/rbd_provisioner.md) + * [CEPHFS Provisioner](docs/kubernetes-apps/cephfs_provisioner.md) + * [Local Volume Provisioner](docs/kubernetes-apps/local_volume_provisioner.md) * Developers * [Test cases](docs/test_cases.md) * [Vagrant](docs/vagrant.md) diff --git a/roles/bootstrap-os/README.md b/docs/bootstrap-os.md similarity index 100% rename from roles/bootstrap-os/README.md rename to docs/bootstrap-os.md diff --git a/roles/kubernetes-apps/ingress_controller/cert_manager/README.md b/docs/cert_manager.md similarity index 100% rename from roles/kubernetes-apps/ingress_controller/cert_manager/README.md rename to docs/cert_manager.md diff --git a/roles/kubernetes-apps/ingress_controller/alb_ingress_controller/README.md b/docs/ingress_controller/alb_ingress_controller.md similarity index 100% rename from roles/kubernetes-apps/ingress_controller/alb_ingress_controller/README.md rename to docs/ingress_controller/alb_ingress_controller.md diff --git a/docs/ambassador.md b/docs/ingress_controller/ambassador.md similarity index 81% rename from docs/ambassador.md rename to docs/ingress_controller/ambassador.md index fbd44a3c0..0185d59ce 100644 --- a/docs/ambassador.md +++ b/docs/ingress_controller/ambassador.md @@ -16,6 +16,16 @@ URL rewriting, CORS, rate limiting, and automatic metrics collection. installation/updates. * `ingress_ambassador_secure_port` (default: 443): HTTPS port to listen at. * `ingress_ambassador_insecure_port` (default: 80): HTTP port to listen at. +* `ingress_ambassador_multi_namespaces` (default `false`): By default, Ambassador will only + watch the `ingress_ambassador_namespace` namespace for `AmbassadorInstallation` CRD resources. + When set to `true`, this value will tell the Ambassador Operator to watch **all** namespaces + for CRDs. If you want to run multiple Ambassador ingress instances, set this to `true`. + +### Ingress annotations + +The Ambassador API Gateway will automatically load balance `Ingress` resources +that include the annotation `kubernetes.io/ingress.class=ambassador`. All the other +resources will be just ignored. ### Ambassador Operator diff --git a/roles/kubernetes-apps/ingress_controller/ingress_nginx/README.md b/docs/ingress_controller/ingress_nginx.md similarity index 100% rename from roles/kubernetes-apps/ingress_controller/ingress_nginx/README.md rename to docs/ingress_controller/ingress_nginx.md diff --git a/docs/metallb.md b/docs/ingress_controller/metallb.md similarity index 100% rename from docs/metallb.md rename to docs/ingress_controller/metallb.md diff --git a/roles/kubernetes-apps/external_provisioner/cephfs_provisioner/README.md b/docs/kubernetes-apps/cephfs_provisioner.md similarity index 90% rename from roles/kubernetes-apps/external_provisioner/cephfs_provisioner/README.md rename to docs/kubernetes-apps/cephfs_provisioner.md index 8af1d0e6b..c5c18db1f 100644 --- a/roles/kubernetes-apps/external_provisioner/cephfs_provisioner/README.md +++ b/docs/kubernetes-apps/cephfs_provisioner.md @@ -1,12 +1,10 @@ -CephFS Volume Provisioner for Kubernetes 1.5+ -============================================= +# CephFS Volume Provisioner for Kubernetes 1.5+ [![Docker Repository on Quay](https://quay.io/repository/external_storage/cephfs-provisioner/status "Docker Repository on Quay")](https://quay.io/repository/external_storage/cephfs-provisioner) Using Ceph volume client -Development ------------ +## Development Compile the provisioner @@ -20,8 +18,7 @@ Make the container image and push to the registry make push ``` -Test instruction ----------------- +## Test instruction - Start Kubernetes local cluster @@ -65,14 +62,12 @@ kubectl create -f example/claim.yaml kubectl create -f example/test-pod.yaml ``` -Known limitations ------------------ +## Known limitations - Kernel CephFS doesn't work with SELinux, setting SELinux label in Pod's securityContext will not work. - Kernel CephFS doesn't support quota or capacity, capacity requested by PVC is not enforced or validated. - Currently each Ceph user created by the provisioner has `allow r` MDS cap to permit CephFS mount. -Acknowledgement ---------------- +## Acknowledgement Inspired by CephFS Manila provisioner and conversation with John Spray diff --git a/roles/kubernetes-apps/external_provisioner/local_volume_provisioner/README.md b/docs/kubernetes-apps/local_volume_provisioner.md similarity index 94% rename from roles/kubernetes-apps/external_provisioner/local_volume_provisioner/README.md rename to docs/kubernetes-apps/local_volume_provisioner.md index b8b444476..283969def 100644 --- a/roles/kubernetes-apps/external_provisioner/local_volume_provisioner/README.md +++ b/docs/kubernetes-apps/local_volume_provisioner.md @@ -1,5 +1,4 @@ -Local Storage Provisioner -========================= +# Local Storage Provisioner The [local storage provisioner](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume) is NOT a dynamic storage provisioner as you would @@ -47,8 +46,7 @@ data: The default StorageClass is local-storage on /mnt/disks, the rest of this doc will use that path as an example. -Examples to create local storage volumes ----------------------------------------- +## Examples to create local storage volumes 1. tmpfs method: @@ -106,8 +104,7 @@ management. Create a symbolic link under discovery directory to the block device on the node. To use raw block devices in pods, volume_type should be set to "Block". -Usage notes ------------ +## Usage notes Beta PV.NodeAffinity field is used by default. If running against an older K8s version, the useAlphaAPI flag must be set in the configMap. @@ -120,7 +117,6 @@ Make sure to make any mounts persist via /etc/fstab or with systemd mounts (for Flatcar Container Linux). Pods with persistent volume claims will not be able to start if the mounts become unavailable. -Further reading ---------------- +## Further reading Refer to the upstream docs here: diff --git a/roles/kubernetes-apps/external_provisioner/rbd_provisioner/README.md b/docs/kubernetes-apps/rbd_provisioner.md similarity index 100% rename from roles/kubernetes-apps/external_provisioner/rbd_provisioner/README.md rename to docs/kubernetes-apps/rbd_provisioner.md diff --git a/roles/kubernetes-apps/registry/README.md b/docs/kubernetes-apps/registry.md similarity index 91% rename from roles/kubernetes-apps/registry/README.md rename to docs/kubernetes-apps/registry.md index 27395afec..77ff08caf 100644 --- a/roles/kubernetes-apps/registry/README.md +++ b/docs/kubernetes-apps/registry.md @@ -1,12 +1,10 @@ -Private Docker Registry in Kubernetes -===================================== +# Private Docker Registry in Kubernetes Kubernetes offers an optional private Docker registry addon, which you can turn on when you bring up a cluster or install later. This gives you a place to store truly private Docker images for your cluster. -How it works ------------- +## How it works The private registry runs as a `Pod` in your cluster. It does not currently support SSL or authentication, which triggers Docker's "insecure registry" @@ -14,8 +12,7 @@ logic. To work around this, we run a proxy on each node in the cluster, exposing a port onto the node (via a hostPort), which Docker accepts as "secure", since it is accessed by `localhost`. -Turning it on -------------- +## Turning it on Some cluster installs (e.g. GCE) support this as a cluster-birth flag. The `ENABLE_CLUSTER_REGISTRY` variable in `cluster/gce/config-default.sh` governs @@ -24,7 +21,7 @@ whether the registry is run or not. To set this flag, you can specify does not include this flag, the following steps should work. Note that some of this is cloud-provider specific, so you may have to customize it a bit. -- Make some storage +### Make some storage The primary job of the registry is to store data. To do that we have to decide where to store it. For cloud environments that have networked storage, we can @@ -58,15 +55,14 @@ If, for example, you wanted to use NFS you would just need to change the Note that in any case, the storage (in the case the GCE PersistentDisk) must be created independently - this is not something Kubernetes manages for you (yet). -- I don't want or don't have persistent storage +### I don't want or don't have persistent storage If you are running in a place that doesn't have networked storage, or if you just want to kick the tires on this without committing to it, you can easily adapt the `ReplicationController` specification below to use a simple `emptyDir` volume instead of a `persistentVolumeClaim`. -Claim the storage ------------------ +## Claim the storage Now that the Kubernetes cluster knows that some storage exists, you can put a claim on that storage. As with the `PersistentVolume` above, you can start @@ -93,8 +89,7 @@ you created before will be bound to this claim (unless you have other `PersistentVolumes` in which case those might get bound instead). This claim gives you the right to use this storage until you release the claim. -Run the registry ----------------- +## Run the registry Now we can run a Docker registry: @@ -145,8 +140,7 @@ spec: ``` -Expose the registry in the cluster ----------------------------------- +## Expose the registry in the cluster Now that we have a registry `Pod` running, we can expose it as a Service: @@ -170,8 +164,7 @@ spec: ``` -Expose the registry on each node --------------------------------- +## Expose the registry on each node Now that we have a running `Service`, we need to expose it onto each Kubernetes `Node` so that Docker will see it as `localhost`. We can load a `Pod` on every @@ -229,8 +222,7 @@ $ curl localhost:5000 404 page not found ``` -Using the registry ------------------- +## Using the registry To use an image hosted by this registry, simply say this in your `Pod`'s `spec.containers[].image` field: @@ -258,15 +250,3 @@ $ kubectl port-forward --namespace kube-system $POD 5000:5000 & Now you can build and push images on your local computer as `localhost:5000/yourname/container` and those images will be available inside your kubernetes cluster with the same name. - -More Extensions ---------------- - -- [Use GCS as storage backend](gcs/README.md) -- [Enable TLS/SSL](tls/README.md) -- [Enable Authentication](auth/README.md) - -Future improvements -------------------- - -- Allow port-forwarding to a Service rather than a pod (\#15180) diff --git a/roles/kubernetes-apps/ingress_controller/ambassador/README.md b/roles/kubernetes-apps/ingress_controller/ambassador/README.md deleted file mode 100644 index b3fac29fe..000000000 --- a/roles/kubernetes-apps/ingress_controller/ambassador/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# Installation Guide - -- [Installation Guide](#installation-guide) - - [Ambassador](#ambassador) - - [Ambassador Operator](#ambassador-operator) - - [Configuration](#configuration) - - [Ingress annotations](#ingress-annotations) - -## Ambassador - -The Ambassador API Gateway provides all the functionality of a traditional ingress controller -(e.g., path-based routing) while exposing many additional capabilities such as authentication, -URL rewriting, CORS, rate limiting, and automatic metrics collection. - -## Ambassador Operator - -This addon deploys the Ambassador Operator, which in turn will install Ambassador in -a kubespray cluster. - -The Ambassador Operator is a Kubernetes Operator that controls Ambassador's complete lifecycle -in your cluster, automating many of the repeatable tasks you would otherwise have to perform -yourself. Once installed, the Operator will complete installations and seamlessly upgrade to new -versions of Ambassador as they become available. - -## Configuration - -- `ingress_ambassador_namespace` (default `ambassador`): namespace for installing Ambassador. -- `ingress_ambassador_update_window` (default `0 0 * * SUN`): _crontab_-like expression - for specifying when the Operator should try to update the Ambassador API Gateway. -- `ingress_ambassador_version` (default: `*`): SemVer rule for versions allowed for - installation/updates. -- `ingress_ambassador_multi_namespaces` (default `false`): By default, Ambassador will only - watch the `ingress_ambassador_namespace` namespace for `AmbassadorInstallation` CRD resources. - When set to `true`, this value will tell the Ambassador Operator to watch **all** namespaces - for CRDs. If you want to run multiple Ambassador ingress instances, set this to `true`. - -## Ingress annotations - -The Ambassador API Gateway will automatically load balance `Ingress` resources -that include the annotation `kubernetes.io/ingress.class=ambassador`. All the other -resources will be just ignored.