davidffrench/mobile-security-service-operator

Mobile Security Service Operator

Project health

Table of Contents

• Overview
• Prerequisites
• Getting Started
  • Cloning the repository
  • Minishift installation and setup
  • Configuring
  • Installing
  • Binding an app
  • Unbinding an app
  • Removing
• Configurations and Options
  • Environment Variables and ConfigMap
  • Role for no-privilege users are able to create the Mobile Security Service App, Database and/or Bind and Unbind their apps
  • Database image and parameters
• Development
  • Architecture
  • Running the operator locally
  • Publishing a new version
  • Using the dev tags
• Using make commands
• Supportability
• Contributing
• Questions

Overview

A Operator based on the Operator SDK to run the Mobile Security Service on a OpenShift/Kubernetes cluster.

Prerequisites

Install Golang

Ensure the $GOPATH environment variable is set

Install the dep package manager

Install Operator-SDK

Install kubectl

Getting Started

Cloning the repository

By the following commands you will create a local directory and clone this project.

$ git clone git@github.com:aerogear/mobile-security-service.git $GOPATH/src/github.com/aerogear/mobile-security-service-operator

Minishift installation and setup

Install Minishift then enable Operators on it by running the following commands.

# create a new profile to test the operator
$ minishift profile set mss-operator

# enable the admin-user add-on
$ minishift addon enable admin-user

# add insecure registry to download the images from docker
$ minishift config set insecure-registry 172.30.0.0/16

# start the instance
$ minishift start

Configuring

Update the cluster host IP into the MobileSecurityService CR

ℹ️	The clusterHost will be used to generated the route/ingress source as in the ConfigMap created with the SDK JSON config.

Installing

Use the following command to create the Operator, Service and its Database as apply the roles on the cluster.

$ make create-all

❗	To create all you need be logged as admin. Use oc login -u system:admin.

Binding an app

• Create a MobileSecurityServiceBind CR as this example.

• The app name and appId need to be specified into the MobileSecurityServiceBind CR as follows.

    # The appName spec defines the name of the app used to bind the service
    appName: "app"
    # The appId spec defines the appId of the app used to bind the service
    appId: "appid"

  ❗	Do not forget to update the clusterHost into the MobileSecurityServiceBind CR

• Run the following command to bind the app to the Mobile Security Service

  $ make bind

Unbinding an app

• Create a MobileSecurityServiceUnbind CR as this example.

• Add into into the MobileSecurityServiceUnbind CR the app id as follows.

    # The appId spec defines the appId of the app used to bind the service
    appId: "appid"

  ❗	Do not forget to update the clusterHost into the MobileSecurityServiceUnbind CR

• Run the following command to unbind the app from the service

  $ make unbind

Removing

Use the following command to delete the Operator, the Service and its Database as roles from the cluster.

$ make delete-all

❗	To create all you need be logged as admin. Use oc login -u system:admin.

Configurations and Options

Environment Variables and ConfigMap

The environment variables are used to configure the Mobile Security Service Application and Database. For a further understatement over its configuration see Setup and Configurations section in Mobile Security Service README.

NOTE:

• All values used in the default configuration came from the config-map which is managed and created by the Operator. This config map will be created in the Operator namespace and its name is defined by the attribute configMapName in the MobileSecurityService CR.

• If the name of this ConfigMap be not specified then the name of the Mobile Security Service instance will be used instead of.

• The MobileSecurityServiceDB and MobileSecurityService should have specified the same name for this ConfigMap in order to allow the App and Database share its usage.

Role for no-privilege users are able to create the Mobile Security Service App, Database and/or Bind and Unbind their apps

By executing the following commands you will create roles in the cluster which will allow the <user> create the Mobile Security Service Application and Database in their namespaces. In this would not be required be the system:admin. However, the Mobile Security Service Operator is cluster scoped and will still only accessible for the `system admin users.

$ oc create rolebinding developer-mobile-security-service-operator --role=mobile-security-service-operator --user=<user>
$ oc create rolebinding developer-mobile-security-service --role=mobile-security-service --user=<user>

Database image and parameters

The database image and its parameters as their default values are configurable and specified by the MobileSecurityServiceDB CR.

Development

Architecture

This operator is cluster-scoped. To know more over it see the topic Operator Scope in the Operator Framework documentation. Also, check its roles in Deploy directory.

ℹ️	The operator, application and database will be installed in the namespace mobile-security-service-operator which will be created by this project.

CRD Definitions

CustomResourceDefinition	Description
MobileSecurityService	Packages, manages, installs and configures the Mobile Security Service on the cluster.
MobileSecurityServiceDB	Packages, manages, installs and configures the Mobile Security Service Database on the cluster.
MobileSecurityServiceBind	Creates and update the app in the Service REST API and create the SDK Config Map.
MobileSecurityServiceUnbind	Delete the app from the Service REST API.

Resources managed by each CRD Controller

• Mobile Security Service

  Resource	Description
  configmaps.go	Define the ConfigMap resources required for the Mobile Security Service Application and its Database. It will create the mobile-security-service-app` which map the values used in the Environment Variables of both.
  deployments.go	Define the Deployment resource of Mobile Security Service Application. (E.g container and resources definitions)
  ingress.go	Define the route/ingress resource required to allow access to the Mobile Security Service Application.
  services.go	Define the Service resource of Mobile Security Service Application.

• Mobile Security Service Database

  Resource	Description
  deployments.go	Define the Deployment resource of Mobile Security Service Database. (E.g container and resources definitions)
  pvs.go	Define the PersistentVolumeClaim resource used by its Database.
  services.go	Define the Service resource of Mobile Security Service Database.

• Mobile Security Service Bind

  Resource	Description
  configmaps.go	Define the ConfigMap resources managed by the Bind. It creates the ConfigMap with the config JSON for the SDK and the app by the REST API. Note that each application has our own Bind CR applied.

Status Definition per Types

• MobileSecurityService

  Status	Description
  appStatus	For this status is expected the value OK which means that all required Kubernetes/OCP objects are created.
  configMapName	Name of the configMap created with the Environment Variables.
  deploymentName	Name of the deployment object created for the App.
  deploymentStatus	Deployment Status from ks8 API. ( v1beta1.DeploymentStatus )
  serviceName	Name of the service object created for the App.
  serviceStatus	Deployment Status from ks8 API. ( v1.ServiceStatus )
  ingressName	Name of the ingress/route object created for the App.
  ingressStatus	Ingress Status from ks8 API. ( v1beta1.IngressStatus )

• MobileSecurityServiceDB

  Status	Description
  databaseStatus	For this status is expected the value OK which means that all required Kubernetes/OCP objects are created.
  deploymentName	Name of the deployment object created for the Database.
  deploymentStatus	Deployment Status from ks8 API. ( v1beta1.DeploymentStatus )
  serviceName	Name of the service object created for the Database.
  serviceStatus	Deployment Status from ks8 API. ( v1.ServiceStatus )
  PersistentVolumeClaimName	Name of the PersistentVolumeClaimName object created for the Database.

• MobileSecurityServiceBind

  Status	Description
  bindStatus	For this status is expected the value OK which means that the app was created in the Rest Service API as its SDKConfigMap.
  SDKConfigMapName	Name of the config map object created for the app with its SDK Config.

• MobileSecurityServiceUnbind

  Status	Description
  unbindStatus	For this status is expected the value OK which means that the app was deleted in the Rest Service API as its SDKConfigMap.

Running the operator locally

The following command will install the operator in the cluster and run the changes performed locally without the need to publish a `dev tag. In this way, you can verify your code in the development environment.

$ make run-local

❗	The local changes are applied when the command operator-sdk up local --namespace=mobile-security-service-operator is executed then it is not a hot deploy and to get the latest changes you need re-run the command.

Publishing a new version

The tags are published into the Docker Hub.

Master tags

To publish an new version of this operator based on the master branch following the steps.

• Update the operator tag version

  Replace the tag of the image in the operator.yaml file.

    # Replace this with the built image name
    image: aerogear/mobile-security-service-operator:0.1.0

  ℹ️	In this example the tag 0.1.0 will be replaced for the new one.

• Replace the tag in the Makefile file.

  TAG=0.1.0

  ℹ️	In this example the tag 0.1.0 will be replaced for the new one.

  ❗	Follow the Semantic Versioning to define the new tags

• Build and publish the new version tag in Docker Hub

  Run the following commands

  $ make build
  $ make publish

ℹ️	You need be logged in the docker and have access to publish images on it. Use $ docker login.

Dev tags

The dev tags will allow you test locally the changes performed in the project without affect the tag published into the Docker Hub based on the master branch. The following commands will build the project and publish it with the tag which will be <version>-dev.

$ make build-dev
$ make publish-dev

ℹ️	You need be logged in the docker and have access to publish images on it. Use $ docker login.

Using the dev tags

Update the image tag in the file operator.yaml with the development tag as follows.

# Replace this with the built image name
image: aerogear/mobile-security-service-operator:0.1.0-dev

ℹ️	The image/tag used from Mobile Security Service is defined in mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml file.

Using make commands

Command	Description
make create-all	Create mobile-security-service-operator namespace, operator, service and roles
make delete-all	Delete mobile-security-service-operator namespace, operator, service and roles
make create-oper	Create mobile-security-service namespace, operator and roles
make delete-oper	Delete mobile-security-service namespace, operator and roles
make create-app	Create Mobile Security Service App and its database in the project
make create-app-only	Create Mobile Security Service App without its database
make delete-app	Delete Mobile Security Service App and its database
make delete-app-only	Delete Mobile Security Service App only
make create-db-only	Create Mobile Security Service Database without its application
make delete-db-only	Delete Mobile Security Service Database only
make bind	Create the Bind CR and delete the Unbind CR examples. (Create/Update app in the Service and add SKD ConfigMap)
make unbind	Delete the Bind CR and create Unbind CR examples. (Delete app from the Service and SDKConfigMap)
make build	Build operator with its tag
make publish	Publish operator in Docker Hub with its tag
make build-dev	Build operator for development proposes
make publish-dev	Publish operator in Docker Hub for development proposes
make run-local	Run the operator locally for development purposes
make vet	Examines source code and reports suspicious constructs using vet
make fmt	Formats code using gofmt

ℹ️	The Makefile is implemented with tasks which you should use to work with.

Supportability

This operator was developed using the k8s APIs and should work well in Kubernetes and OpenShift clusters. However, it has been tested on OpenShift clusters only so far.

Contributing

All contributions are hugely appreciated. Please see our Contributing Guide for guidelines on how to open issues and pull requests. Please check out our Code of Conduct too.

Questions

There are a number of ways you can get in in touch with us, please see the AeroGear community.