lifecycle-service

A service responsible for managing CrateKube platform services and upgrades

Introduction

The lifecycle service is part of an MVaP architecture and set of requirements for CrateKube. This microservice can operate as an independent API, however it is designed as part of a larger system in order to provide a hybrid-cloud management platform that is default-secure and ephemeral with elastic provisioning, hardened pod security policies, self-healing event-driven architecture, and persistent storage.

Quick links

CrateKube operator documentation
System Architecture and high-level Requirements
How to contribute
Contributor architecture, roles and responsibilities, and developer documentation

What does this service do?

The lifecycle-service is in charge of managing the lifecycle of all CrateKube platform services (known as managed components), including itself. These managed components run in a Kubernetes cluster and the lifecycle-service uses kubectl to perform management operations.

There are three default managed components: cloud-mgmt-service, cluster-mgmt-service, and lifecycle-service. Each managed component, including the lifecycle-service itself, contains a deployment.yml file in the root of its GitHub repository with Kubernetes NodePort Service and Deployment resources. This deployment.yml file is used by the lifecycle-service to deploy the managed component .

The lifecycle-service manages Deployments using matchLabels. The matchLabels key used is name and its value is the name of the managed component's repository. The name of the container must also match the repository name, for example: lifecycle-service, cloud-mgmt-service and cluster-mgmt-service. A good example of the necessary configuration is the lifecycle-service's deployment.yml.

Versions of deployment.yml are managed by release (tag) and if a managed component does not exist on the Kubernetes cluster the lifecycle-service is configured to manage, the latest version (retrieved from the repositories API endpoint/tags) is used to retrieve the deployment.yml and deploy it. This behavior can be overridden for each managed compent by providing the CLUSTER_MGMT_ENABLED, CLOUD_MGMT_ENABLED, or LIFECYCLE_ENABLED environment variables with false values when running the application

The lifecycle-service uses a kubeconfig file to communicate with the Kubernetes cluster. This defaults to /app/kube/kubeconfig and can be changed by providing the KUBE_CONFIG_LOCATION environment variable when running the application.

Quickstart

To run this service, simply execute:

docker run -p 8080:9000 -v /path/to/kube/config:/app/kube/kubeconfig cratekube/lifecycle-service

Note: We are bind mounting a kubeconfig /path/to/kube/config file inside of the container at /app/kube/kubeconfig in order for kubectl to execute successfully.

Development

Configuration

Internal and external services are configured by extending the Dropwizard application configuration with additional settings. An environment variable parser is used to allow configuration settings to be overridden at runtime. These configuration options can be seen in the app config file.

How this app works

This application utilizes two Dropwizard Quartz Integration scheduled jobs to assist in managing the lifecycle of CrateKube platform components.

The UpgradeAvailabilityJob is responsible for retrieving and caching the configuration and deployed version of managed platform components from Kubernetes using kubectl, and the latest version by querying GitHub. This information is used to expose managed component upgrade availability.

The ComponentDeploymentJob deploys the latest version of managed components enabled for deployment that are not currently running in Kubernetes by retrieving deployment yaml located in its GitHub repository and applying it via kubectl.

This service can act as a stand-alone service for managing any Kubernetes deployable yaml as long as it conforms to the conventions outlined above. It can be easily extended by forking and developing as a CrateKube contributor.

Building with Docker

We strive to have our builds repeatable across development environments so we also provide a Docker build to generate the Dropwizard application container. The examples below should be executed from the root of the project.

Run the base docker build:

docker build -t lifecycle-service:local --target build .

Note: This requires docker 19.03.x or above. Docker 18.09 will throw errors for mount points and the --target flag.

Build the package target:

docker build -t lifecycle-service:local --target package .

Run the docker application locally on port 8080:

docker run -p 8080:9000 -v /path/to/kube/config:/app/kube/kubeconfig -d lifecycle-service:local

Building with Gradle

This project uses gradle for building and testing. We also use the gradle wrapper to avoid downloading a local distribution. The commands below are helpful for building and testing.

./gradlew build compile and build the application
./gradlew check run static code analysis and test the application
./gradlew shadowJar builds a fat jar that can be used to run the Dropwizard application
./gradlew buildClient generates the API client code for the Dropwizard application
./gradlew publishToMavenLocal publishes any local artifacts to the local .m2 repository

After you have generated the fat jar you can run your application with java using:

KUBE_CONFIG_LOCATION=/path/to/kube/config java -jar build/libs/lifecycle-service-1.0.0-SNAPSHOT-all.jar

Note: We are using the KUBE_CONFIG_LOCATION environment variable to specify the path to a kubeconfig /path/to/kube/config file in order for kubectl to execute successfully.

API Documentation

The API docs for this project are powered by the Swagger Specification. After starting up the application the available APIs can be found at http://localhost:8080/swagger

Note: The POST endpoint requires API bearer token authentication. The token value can be configured by providing the ADMIN_APIKEY environment variable when running the application. The default value is eknvDrmcDtseeieSMTvngo

Using the API

The API has endpoints that allow you to retrieve component upgrade availability and deploy specific managed component versions.

The resulting operations exist as REST endpoints, which you can hit in your browser or with a tool such as Postman.

HTTP Verb	Endpoint	Payload	Authorization	Function
GET	/component/version	None	None	Retrieve a list of all managed components with upgrade availability
GET	/component/{name}	None	None	Retrieve a specific managed component with upgrade availability
POST	/component/{name}/version	`{"version":"string"}`	API bearer token	Deploy a specific version of a managed component

API client

This application generates a client for the Dropwizard application by using the swagger specification. The maven asset is available in JCenter, make sure you include the JCenter repository (https://jcenter.bintray.com/) when pulling this client. To use the client provide the following dependency in your project:

Gradle:

implementation 'io.cratekube:lifecycle-service:1.0.0'

Maven:

<dependency>
  <groupId>io.cratekube</groupId>
  <artifactId>lifecycle-service</artifactId>
  <version>1.0.0</version>
</dependency>

Contributing

If you are interested in contributing to this project please review the contribution guidelines. Thank you for your interest in CrateKube!