Adding cloudstack-kubernetes-provider docs

source/plugins/cloudstack-kubernetes-provider.rst

@@ -0,0 +1,153 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+The CloudStack Kubernetes Provider
+==================================
+
+Introduction
+------------
+
+The CloudStack Kubernetes Provider facilitates Kubernetes deployments on Cloudstack.
+It allows Kubernetes to dynamically allocate IP addresses and the respective networking
+rules on CloudStack to ensure seamless TCP, UDP and TCP-Proxy LoadBalancer deployments
+on Kubernetes.
+
+It also automatically manages these rules modifying them based on the deployment as well
+as the size of the cluster.
+
+It was initially the Cloudstack provider in Kubernetes which was later extracted to allow
+for pluggable providers.
+
+The Prebuilt containers are available on `Docker Hub <https://hub.docker.com/r/apache/cloudstack-kubernetes-provider>`_.
+
+Deployment
+----------
+The CloudStack Kubernetes Provider is automatically deployed when a Kuberentes Cluster is
+created on CloudStack 4.16+
+
+In order to communicate with CloudStack, a separate service user **kubeadmin** is created
+in the same account as the cluster owner. The provider uses this user's API keys to get
+the details of the cluster as well as update the networking rules. It is imperative that
+this user is not altered or have its keys regenerated.
+
+The provider can also be manually deployed with instructions `here
+<https://github.com/apache/cloudstack-kubernetes-provider/blob/main/README.md>`_
+
+Further details as well as instructions on how to build and contribute to the project can be found `here
+<https://github.com/apache/cloudstack-kubernetes-provider/blob/main/README.md>`_
+
+Usage
+-----
+
+In the following example, a LoadBalancer Service is created to balance traffic between the nodes in
+a cluster. The DaemonSet creates pods and maps the ports on the pods to the same ports on the host.
+The LoadBalancer creates an externally-accessible IP address that sends traffic to the correct port
+on the cluster nodes.
+
+#. The following yaml creates a DaemonSet which brings up a pod on every node and maps port 80 and
+   443 from the pod to the node. The LoadBalancer Service then creates a public IP to balance traffic
+   on port 80 and 443 between the nodes.
+
+   .. parsed-literal::
+      ---
+      apiVersion: v1
+      kind: Service
+      metadata:
+      name: traefik
+      annotations:
+         service.beta.kubernetes.io/cloudstack-load-balancer-proxy-protocol: enabled
+      spec:
+      type: LoadBalancer
+      ports:
+      - name: http
+        port: 80
+        targetPort: http
+      - name: https
+        port: 443
+        targetPort: https
+      ---
+      apiVersion: v1
+      kind: ConfigMap
+      metadata:
+      name: traefik-conf
+      data:
+      traefik.toml: |
+         defaultEntryPoints = ["http"]
+         [entryPoints]
+            [entryPoints.http]
+            address = ":80"
+            [entryPoints.http.proxyProtocol]
+            trustedIPs = ["127.0.0.1/32", "10.0.0.1/32"]
+            [entryPoints.https]
+            address = ":443"
+            [entryPoints.https.proxyProtocol]
+            trustedIPs = ["127.0.0.1/32", "10.0.0.1/32"]
+      ---
+      apiVersion: apps/v1
+      kind: DaemonSet
+      metadata:
+      name: traefik-ingress-controller
+      spec:
+      selector:
+         matchLabels:
+            name: traefik-ingress-controller
+      template:
+         metadata:
+            labels:
+            name: traefik-ingress-controller
+         spec:
+            hostNetwork: true
+            containers:
+            - args:
+            - --configfile=/config/traefik.toml
+            image: traefik:1.7.12
+            imagePullPolicy: Always
+            name: traefik-ingress
+            ports:
+            - containerPort: 80
+               hostPort: 80
+               name: http
+               protocol: TCP
+            - containerPort: 443
+               hostPort: 443
+               name: https
+               protocol: TCP
+            volumeMounts:
+            - mountPath: /config
+               name: config
+            volumes:
+            - configMap:
+               defaultMode: 420
+               name: traefik-conf
+            name: config
+
+   It can be deployed by running the command
+
+   .. parsed-literal::
+      kubectl apply -f https://raw.githubusercontent.com/apache/cloudstack-kubernetes-provider/main/traefik-ingress-controller.yml
+
+#. On successfully deploying the yaml file, a new Public IP Address in the same network
+   as the cluster will be created. It will automatically have the firewall and port forwarding
+   rules configured to distribute any traffic amongst the cluster worker nodes
+
+|ckp-ip.png|
+
+|ckp-ip-fw.png|
+
+|ckp-ip-lb.png|
+
+.. |ckp-ip.png| image:: /_static/images/ckp-ip.png
+.. |ckp-ip-fw.png| image:: /_static/images/ckp-ip-fw.png
+.. |ckp-ip-lb.png| image:: /_static/images/ckp-ip-lb.png

source/plugins/index.rst

@@ -37,4 +37,5 @@ This is the Apache CloudStack Plugins guide. This section gives information for
    ipv6
    quota
    cloudstack-kubernetes-service
+   cloudstack-kubernetes-provider.rst