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-acm-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 Supported message Broker are DMaap and Strimzi-Kafka.
  14
  15 The kubernetes participant also exposes REST endpoints for onboarding, installing and uninstalling of helm charts from the
  16 local chart database which facilitates the user to also use this component as a standalone application for helm operations.
  17
  18 By Kohn version, the kubernetes participant supports the following methods of installation of helm charts.
  19
  20 - Installation of helm charts from configured helm repositories and remote repositories passed via TOSCA in CLAMP.
  21
  22 Prerequisites for using Kubernetes participant in Istanbul version:
  23 -------------------------------------------------------------------
  24
  25 - A running Kubernetes cluster.
  26
  27   Note:
  28
  29   - 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.
  30
  31   - 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.
  32
  33     Example: `kubectl create clusterrolebinding k8s-participant-admin-binding --clusterrole=cluster-admin --serviceaccount=<k8s participant service account>`
  34
  35
  36 .. image:: ../../images/participants/k8s-participant.png
  37
  38 Supported Element Types
  39 -----------------------
  40 Supported Element Types for Kubernetes participant will be used to define the Kubernetes participant Element Definition Types in tosca template.
  41 Participant Supported Element Types is defined in Kubernetes participant application.yaml.
  42
  43 .. code-block:: YAML
  44
  45     participantSupportedElementTypes:
  46       -
  47         typeName: org.onap.policy.clamp.acm.K8SMicroserviceAutomationCompositionElement
  48         typeVersion: 1.0.0
  49
  50 Defining a TOSCA CL definition for kubernetes participant:
  51 ----------------------------------------------------------
  52
  53 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.
  54 A Automation Composition 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 Automation Composition Element.
  55
  56 Sample tosca template defining a participant and a AC element definition. :download:`click here <tosca/tosca-k8s-participant.yml>`
  57
  58
  59 Configuring a Automation Composition Element on the kubernetes participant for a Automation Composition
  60 -------------------------------------------------------------------------------------------------------
  61
  62 The user defines the following properties in the TOSCA template for the kubernetes participant:
  63
  64 .. list-table::
  65    :widths: 15 10 50
  66    :header-rows: 1
  67
  68    * - Property
  69      - Type
  70      - Description
  71    * - chartId
  72      - ToscaConceptIdentifier
  73      - The name and version of the helm chart that needs to be managed by the kubernetes participant
  74    * - namespace
  75      - String
  76      - The namespace in the k8s cluster where the helm chart needs to be installed
  77    * - releaseName
  78      - String
  79      - The helm deployment name that specifies the installed component in the k8s cluster
  80    * - repository (optional)
  81      - map
  82      - A map of *<String, String>* defining the helm repository parameters for the chart
  83    * - overrideParams (optional)
  84      - map
  85      - A map of *<String, String>* defining the helm chart parameters that needs to be overridden
  86
  87 Note: The repository property can be skipped if the helm chart is available in the local chart database or
  88 in a repository that is already configured on the helm client. The participant does a chart lookup by default.
  89
  90 The *repository* type is described in the following table:
  91
  92 .. list-table::
  93    :widths: 15 10 50
  94    :header-rows: 1
  95
  96    * - Field
  97      - Type
  98      - Description
  99    * - repoName
 100      - String
 101      - The name of the helm repository that needs to be configured on the helm client
 102    * - address
 103      - String
 104      - Specifies the url of the hem repository
 105    * - userName (optional)
 106      - String
 107      - The username to login the helm repository
 108    * - password (optional)
 109      - String
 110      - The password to login the helm repository
 111
 112 Sample Automation Composition instances.
 113 In that example the user fills the properties defined in the TOSCA for the Kubernetes participant :download:`click here <tosca/automation-composition-k8s.yml>`
 114
 115 Kubernetes participant Interactions:
 116 ------------------------------------
 117 The kubernetes participant interacts with Automation Composition Runtime on the northbound via Message Broker. It interacts with the helm client on the southbound for performing various helm operations to the k8s cluster.
 118
 119 The communication for the Automation Composition updates and state change requests are sent from the Automation Composition Runtime to the participant via Message Broker.
 120 The participant performs appropriate operations on the k8s cluster via helm client based on the received messages from the Automation Composition Runtime.
 121
 122
 123 kubernetes participant Workflow:
 124 --------------------------------
 125 Once the participant is started, it sends a "REGISTER" event to the Message Broker topic which is then consumed by the Automation Composition Runtime to register this participant on the runtime database.
 126 The user can commission the tosca definitions from the Policy Gui to the Automation Composition Runtime.
 127 Once the automation composition definitions are available in the runtime database, the user can prime them and further updates the participant with these definitions via Message Broker.
 128 After primed, the Automation Composition can be instantiated with the default state "UNDEPLOYED" from the Policy Gui.
 129
 130 When the state of the Automation Composition is changed from "UNDEPLOYED" to "DEPLOYED" from the Policy Gui, the kubernetes participant receives the automation composition state change event from the runtime and
 131 deploys the helm charts associated with each Automation Composition Elements by creating appropriate namespace on the cluster.
 132 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.
 133
 134 The participant also monitors the deployed pods for the configured time until the pods comes to RUNNING state.
 135 It holds the deployment information of the pods including the current status of the pods after the deployment.
 136
 137 When the state of the Automation Composition is changed from "DEPLOYED" to "UNDEPLOYED" back, the participant also undeploys the helm charts from the cluster that are part of the Automation Composition Element.