AMP Kubernetes Integration

This project provides an Cloudsoft AMP bundle with entities and utilities for management of Kubernetes configuration. Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications.

Build

Clone the project then change to the newly created repository and run:

mvn clean install

Install

Use the AMP CLI to add the resulting bundle to the catalog(or import it from the GUI):

br catalog add target/brooklyn-kubernetes-1.1.0-SNAPSHOT.jar

Use

Note If you installed the project with catalog.bom then you can use the entity by using type kubernetes-discovery. If you installed the dependencies manually then you should refer to the Java type io.cloudsoft.kubernetes.discovery.KubernetesDiscovery instead. Examples below refer to kubernetes-discovery.

The entity is designed to connect to an existing Kubernetes deployment to allow AMP control over the deployed entities.

An AMP location is required for AMP to connect to the Kubernetes deployment. An example is provided in test/resources/sockshop-location.yaml and is used for the Sock Shop examples below.

Deploying Sock Shop

The example below assume that a modified version of the microservices sockshop has been installed on minikube. This modified version includes extra labels which are used by AMP to automatically organise the entities retrieved from the Kubernetes deployment.

To install this version of sock shop, follow the instructions in demo/README.md. If minikube is already configured appropriately, the following command should work:

kubectl create -f demo/sock-shop

Note The kubectl configuration must point at the same Kubernetes infrastructure as the configuration in the AMP KubernetesLocation being used.

Deploying the Example

Once Kubernetes and AMP have been setup, you can now deploy the example blueprint. This is located in test/resources/sockshop-discovered.yaml. To deploy it, run the following command:

br deploy test/resources/sockshop-discovered.yaml

Example Blueprint

The example blueprint starts with the following section:

services:
  - type: kubernetes-discovery
    name: Discovered Entities
    location: kubernetes-sockshop
    brooklyn.initializers:
      - type: kubernetes-labels-compliance-check
    brooklyn.config:
      namespace: sock-shop
      kubernetes.auto-organize-labels: true

This instructs AMP to connect to the Kubernetes deployment via the kubernetes-sockshop location. The kubernetes-discovery entity will then search for Kubernetes Pods, Services, etc. and create AMP entities representing those discovered.

The brooklyn.initializers section adds a compliance check that verifies common Kubernetes labels are set against discovered resources.

The kubernetes.auto-organize-labels config key instructs the Kubernetes Discovery entity to create an Auto-Managed Applications entity, under which the Pods, Services etc. will be automatically arranged, based on the common labels suggested in the Kubernetes documentation.

Note The default value for this config key is true, so it is not strictly necessary to provide it, but it is included here for clarity. To disable auto-management, set the value of this key to false.

The remainder of the example shows how to provide your own structure for the managed application, should you not wish to use auto-arrangement.

The org.apache.brooklyn.entity.group.DynamicGroup is used to create a dynamically-updated group of entities matching certain criteria by means of a Guava Predicate passed via the dynamicgroup.entityfilter config key.

Documentation

The bundle provides the following types, which are made available in the Catalog.

Entities

kubernetes-discovery

The main discovery entity. This connects to a KubernetesLocation and discovers all resources created under a particular namespace. The following configuration keys are available:

namespace - The Kubernetes namespace to use when searching for resources.
kubernetes.auto-organize-labels - Whether to automatically arrange discovered entities in a hierarchy based on the values of common Kubernetes labels. This defaults to true.
kubernetes.health-check.period - The period between discovery status update checks. This defaults to 1 minute.

Predicates

These predicates are available to structure the discovered Kubernetes resource entities into groups based on various properties they have.

kubernetes-discovery-predicate-is-pod

This predicate will restrict the group to entities representing a Kubernetes Pod and is used as follows:

- $brooklyn:object:
    type: kubernetes-discovery-predicate-is-pod

kubernetes-discovery-predicate-has-label

This predicate takes two parameters, first the label name, and secondly the string to be matched. It will limit the entities to those with the specified label having a value matching the one provided.

The following will match resources with the label owner having the value brooklyn:

- $brooklyn:object:
    type: kubernetes-discovery-predicate-has-label
    constructor.args:
      - "owner"
      - "brooklyn"

kubernetes-discovery-predicate-name-matches

This predicate takes a regex value and will limit entities to those with a name matching the regex parameter. See the Java documentation for details of the syntax accepted.

The following will match any name beginning either foo1bar or foo2bar:

- $brooklyn:object:
    type: kubernetes-discovery-predicate-name-matches
    constructor.args:
      - "^foo[12]bar"

Initializers

kubernetes-labels-compliance-check

This initializer adds a compliance check to the AMP dashboard that verifies whether the discovered entities are using the suggested common labels from the Kubernetes documentation, as is best practice when creating Kubernetes applications. The following configuration keys are available:

kubernetes.default-labels - Whether to check for the set of common Kubernetes label groups. This defaults to true.
custom.labels - Supplies an additional list of extra labels to check for.
labels-check.enabled - Enables the labels check for all discovered resources. This defaults to true, and should not normally need to be reconfigured.

The common labels are split into two groups, Application and Management, and any custom labels will be checked in a group named Custom. The initializer would typically be configured as follows, which specifies two extra custom labels.

brooklyn.initializers:
  - type: kubernetes-labels-compliance-check
    brooklyn.config:
      kubernetes.default-labels: true
      custom.labels: [ "io.cloudsoft/application-id", "io.cloudsoft/entity-id" ]