Skip to content
SmartKey's Kubernetes KMS plugin
Java Go Other
Branch: master
Clone or download
Latest commit 46ebb69 Oct 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
v1beta1 ESS-474 go language based Kubernetes KMS implementation Apr 11, 2019
LICENSE Adding Apache 2.0 License file Aug 13, 2019
Makefile add dependencies May 21, 2019 update May 23, 2019
server.go ESS-644 Add validation for API key, AES key uuid and iv Jun 4, 2019
server_test.go ESS-644 Add validation for API key, AES key uuid and iv Jun 4, 2019
smartkeymethods.go ESS-644 Add validation for API key, AES key uuid and iv Jun 10, 2019
smartkeymethods_test.go added-test-cases May 8, 2019

SmartKey Kubernetes KMS Plugin

This project allows you to use SmartKey as a Key Management Service (KMS) provider for Kubernetes. Refer to to understand how Kubernetes works with an external KMS.

Before you start:

  1. GoLang must be installed in the server you want to build the project on/create installer (Running the installer does not require GoLang).
  2. Existing Kubernetes cluster must be configured to run "SmartKey Kubernetes KMS Plugin".
  3. In order to build/run code or to create the installer, git pull this project into your go directory (eg: ~/go/src/)

Getting Started (Developer)

Checkout a current version of the project.

To test, build or clean the project (from within the project)

This is only for developers who want to build a binary of the gRPC server manually or to execute unit test cases.

  • To test code, run the below command

      $ make test
  • To build code, run the below command

      $ make build
  • To clean workspace, run the below command

      $ make clean
To generate smartkey-kms binary using build command

For developers who want to run the gRPC server directly without using an installer, follow these steps.

  • Execute the following commands to run the binary.

    make build (to build your code and get smartkey-kms)
    sudo ./smartkey-kms --socketFile <sock-file-path> --config <config-file->
    • <sock-file-path>: Path where you want to create your unix socket file eg: /etc/smartkey/smartkey.socket
    • <config-file>: Path to your config file. (eg. conf/smartkey-grpc.conf)
    • Note: <sock-file-path> must already exist (eg. /etc/smartkey). If not, please create before running server.
To create a Debian installer from plugin binary
  • Install these tools

    sudo apt-get install dh-make
    sudo apt-get install devscripts build-essential lintian
  • Execute the script "". It will create .deb file in one level above your PWD


Instead of building code manually (as mentioned in Getting started (Developer) section), we can install the plugin using the compiled .deb file created in the previous step To create a Debian installer from plugin binary.

To install and configure the plugin from Debian installer

  • Execute this command to install the package

    sudo dpkg -i smartkey-kmsplugin_1.0-1_amd64.deb
  • The above command will only install the plugin binary in your machine but will not start it.

  • Note: We will need to do configure our config files before starting service.

  • Update the configuration at "/etc/smartkey/smartkey-grpc.conf".

    Sample "smartkey-grpc.conf" file

      "smartkeyApiKey": "<smartkey-api-key>",
      "encryptionKeyUuid": "<uuid-for-aes-encryption-key-in-SmartKey>",
      "iv": "<Initialization vector for your AES algo as per your key size (128, 192, 256)>",
      "socketFile": "<path-to-your-sock-file>",
      "smartkeyURL": "<smartkey-url>"
  • Execute the following command to run the plugin gRPC server

    sudo service smartkey-grpc start &
  • Verify if the service was started correctly using this command

    sudo service smartkey-grpc status

Configuring the api-server to use "SmartKey Kubernetes KMS Plugin"

For both methods,

  1. running plugin manually or
  2. running the "smartkey-grpc" service created by the installer,

we need to follow these steps.

  1. Open "/etc/kubernetes/manifests/kube-apiserver.yaml" file and add the below configuration.

     - spec.containers.command.kube-apiserver
  2. The installer will automatically create "smartkey.yaml" and copy it to the desired (/etc/smartkey/) location with pre-populated configuration.

  3. Add "volumemount" and "volume host path" to "kube-apiserver.yaml". Without following configurations, api-server will not be able to read "smartkey.yaml" and "smartkey.sock" files.

        - mountPath: /etc/smartkey
            name: smartkey-kms
            readOnly: true
        - hostPath:
            path: /etc/smartkey
            type: DirectoryOrCreate
          name: smartkey-kms

    **Installer will not add these configurations. They need to be manually added to "kube-apiserver.yaml".

  4. Save "kube-apiserver.yaml" and exit. api-server will now detect changes in "kube-apiserver.yaml" file and restart.

Verifying if plugin is configured correctly

  • Create a new secret and you should be able to see logs in the plugin service logs.

  • Use this command to see logs

     journalctl -xe
  • To create a new secret which will be encrypted by our plugin, use this command

     kubectl create secret generic install3 -n default --from-literal=es-engkey=equinixdata
  • To encrypt all of your existing secrets, use this command

     kubectl get secrets --all-namespaces -o json | kubectl replace -f -


  1. Permission denied error while trying to encrypt old secrets using below command Create new secret and you should be able to see logs in plugin service logs.

     $ kubectl get secrets --all-namespaces -o json | kubectl replace -f -

    Fix: Make sure that kubernetes config directory has the same permissions as kubernetes config file.

     $ mkdir -p $HOME/.kube
     $ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
     $ sudo chown $(id -u):$(id -g) $HOME/.kube/config 

    Add change permissions on $HOME/.kube/ directory.

     $ sudo chown $(id -u):$(id -g) $HOME/.kube/
  2. For error "go get: no install location for directory" execute below commands.

     export GOBIN=$HOME/work/bin
     export GOPATH=$HOME/go
  3. In order to uninstall debian package use below command.

     sudo dpkg -P smartkey-kmsplugin

Support email

For any queries, contact ES-ENG-SECURITY

You can’t perform that action at this time.