docs/clamp/acm/design-impl/participants/k8s-participant.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. _clamp-controlloop-k8s-participant:
   4
   5 Kubernetes Participant
   6 ######################
   7
   8 The kubernetes participant receives a helm chart information from the CLAMP runtime and installs the helm chart in to the
   9 k8s cluster on the specified namespace. It can fetch the helm chart from remote helm repositories as well as from any of the repositories
  10 that are configured on the helm client. The participant acts as a wrapper around the helm client and creates the required
  11 resources in the k8s cluster.
  12
  13 The kubernetes participant also exposes REST endpoints for onboarding, installing and uninstalling of helm charts from the
  14 local chart database which facilitates the user to also use this component as a standalone application for helm operations.
  15
  16 In Istanbul version, the kubernetes participant supports the following methods of installation of helm charts.
  17
  18 - Installation of helm charts from configured helm repositories and remote repositories passed via TOSCA in CLAMP.
  19 - Installation of helm charts from the local chart database via the participant's REST Api.
  20
  21 Prerequisites for using Kubernetes participant in Istanbul version:
  22 -------------------------------------------------------------------
  23
  24 - A running Kubernetes cluster.
  25
  26   Note:
  27
  28   - If the kubernetes participant is deployed outside the cluster , the config file of the k8s cluster needs to be copied to the `./kube` folder of kubernetes participant's home directory to make the participant work with the external cluster.
  29
  30   - If the participant needs additional permission to create resources on the cluster, cluster-admin role binding can be created for the service account of the participant with the below command.
  31
  32     Example: `kubectl create clusterrolebinding k8s-participant-admin-binding --clusterrole=cluster-admin --serviceaccount=<k8s participant service account>`
  33
  34
  35 .. image:: ../../images/participants/k8s-participant.png
  36
  37 Defining a TOSCA CL definition for kubernetes participant:
  38 ----------------------------------------------------------
  39
  40 A *chart* parameter map describes the helm chart parameters in tosca template for a microservice that is used by the kubernetes participant for the deployment.
  41 A Control Loop element in TOSCA is mapped to the kubernetes participant and also holds the helm chart parameters for a microservice defined under the properties of the Control Loop Element.
  42
  43 Sample tosca template defining a participant and a control loop element for a control loop. :download:`click here <tosca/tosca-k8s-participant.yml>`
  44
  45
  46 Configuring a Control Loop Element on the kubernetes participant for a Control Loop
  47 -----------------------------------------------------------------------------------
  48
  49 The user configures the following properties in the TOSCA template for the kubernetes participant:
  50
  51 .. list-table::
  52    :widths: 15 10 50
  53    :header-rows: 1
  54
  55    * - Property
  56      - Type
  57      - Description
  58    * - chartId
  59      - ToscaConceptIdentifier
  60      - The name and version of the helm chart that needs to be managed by the kubernetes participant
  61    * - namespace
  62      - String
  63      - The namespace in the k8s cluster where the helm chart needs to be installed
  64    * - releaseName
  65      - String
  66      - The helm deployment name that specifies the installed component in the k8s cluster
  67    * - repository (optional)
  68      - map
  69      - A map of *<String, String>* defining the helm repository parameters for the chart
  70    * - overrideParams (optional)
  71      - map
  72      - A map of *<String, String>* defining the helm chart parameters that needs to be overridden
  73
  74 Note: The repository property can be skipped if the helm chart is available in the local chart database or
  75 in a repository that is already configured on the helm client. The participant does a chart lookup by default.
  76
  77 The *repository* type is described in the following table:
  78
  79 .. list-table::
  80    :widths: 15 10 50
  81    :header-rows: 1
  82
  83    * - Field
  84      - Type
  85      - Description
  86    * - repoName
  87      - String
  88      - The name of the helm repository that needs to be configured on the helm client
  89    * - protocol
  90      - String
  91      - Specifies http/https protocols to connect with repository url
  92    * - address
  93      - String
  94      - Specifies the ip address or the host name
  95    * - port (optional)
  96      - String
  97      - Specifies the port where the repository service is running
  98    * - userName (optional)
  99      - String
 100      - The username to login the helm repository
 101    * - password (optional)
 102      - String
 103      - The password to login the helm repository
 104
 105
 106 Kubernetes participant Interactions:
 107 ------------------------------------
 108 The kubernetes participant interacts with Control Loop Runtime on the northbound via DMaap. It interacts with the helm client on the southbound for performing various helm operations to the k8s cluster.
 109
 110 The communication for the Control loop updates and state change requests are sent from the Control Loop Runtime to the participant via DMaap.
 111 The participant performs appropriate operations on the k8s cluster via helm client based on the received messages from the Control Loop Runtime.
 112
 113
 114 kubernetes participant Workflow:
 115 --------------------------------
 116 Once the participant is started, it sends a "REGISTER" event to the DMaap topic which is then consumed by the Control Loop Runtime to register this participant on the runtime database.
 117 The user can commission the tosca definitions from the Policy Gui to the Control Loop Runtime that further updates the participant with these definitions via DMaap.
 118 Once the control loop definitions are available in the runtime database, the Control Loop can be instantiated with the default state "UNINITIALISED" from the Policy Gui.
 119
 120 When the state of the Control Loop is changed from "UNINITIALISED" to "PASSIVE" from the Policy Gui, the kubernetes participant receives the control loop state change event from the runtime and
 121 deploys the helm charts associated with each Control Loop Elements by creating appropriate namespace on the cluster.
 122 If the repository of the helm chart is not passed via TOSCA, the participant looks for the helm chart in the configured helm repositories of helm client.
 123 It also performs a chart look up on the local chart database where the helm charts are onboarded via the participant's REST Api.
 124
 125 The participant also monitors the deployed pods for the next 3 minutes until the pods comes to RUNNING state.
 126 It holds the deployment information of the pods including the current status of the pods after the deployment.
 127
 128 When the state of the Control Loop is changed from "PASSIVE" to "UNINITIALISED" back, the participant also undeploys the helm charts from the cluster that are part of the Control Loop Element.
 129
 130 REST APIs on Kubernetes participant
 131 -----------------------------------
 132
 133 Kubernetes participant can also be installed as a standalone application which exposes REST endpoints for onboarding,
 134 installing, uninstalling helm charts from local chart database.
 135
 136
 137 .. image:: ../../images/participants/k8s-rest.png
 138
 139 :download:`Download Kubernetes participant API Swagger <swagger/k8s-participant-swagger.json>`