Komiser configurations

From Komiser v3 onwards we specify our komiser configuration by way of a config.toml file. If you place the config.toml file in the same directory as the Komiser binary then it will pick it up by default, if it’s placed in a different location, then we need to pass in the path using the --config flag.

Example start command

komiser start 

Config.toml file


Komiser now supports multiple cloud accounts by default. Account configuration is done through the config.toml file, using either the ENVIRONMENT_VARIABLES or CREDENTIALS_FILE.

Data persistence

Choose between these two methods of persisting your AWS Account data.

Postgres

Add to config.toml file

[postgres]
uri="postgres://postgres:komiser@localhost:5432/komiser?sslmode=disable"
For Postgres, Komiser anticipates the existence of a role postgres and a database komiser on the local Postgres server.

SQLite

Add to config.toml file

[sqlite]
  file = "komiser.db"
The reason for this external data persistence is to improve the filtering, sorting and tagging management experience making it faster and smoother. It also serves as a standalone DB which you are free to query and visualize as you see fit.

Example config.toml

[[aws]]
name="sandbox"
source="CREDENTIALS_FILE"
path="./path/to/credentials/file"
profile="default"

[[aws]]
name="staging"
source="CREDENTIALS_FILE"
path="./path/to/credentials/file"
profile="staging-account"

[[gcp]]
name="production"
source="ENVIRONMENT_VARIABLES"
# path="./path/to/credentials/file" specify if CREDENTIALS_FILE is used
profile="production"

[postgres]
uri="postgres://postgres:komiser@localhost:5432/komiser?sslmode=disable"

Configuring Credentials

When using the CLI you’ll generally need your AWS credentials to authenticate with AWS services. Komiser supports multiple methods of providing these credentials. By default the CLI will source credentials automatically from its default credential chain. In the source section of the cloud profile inside the config.toml file we can choose between ENVIRONMENT_VARIABLES or CREDENTIALS_FILE

Environment Credentials - Set of environment variables that are useful when sub processes are created for specific roles. Useful for local development

[[gcp]]
name="production"
source="ENVIRONMENT_VARIABLES"
profile="production"

EC2 Instance Role Credentials - Use EC2 Instance Role to assign credentials to application running on an EC2 instance. This removes the need to manage credential files in production.

[[aws]]
name="sandbox"
source="CREDENTIALS_FILE"
path="./path/to/credentials/file"
profile="default"

Credentials file

It is not recommended to add your AWS Access and Secret Access key in the credentials file in production. The most secure way of authentication is by using temporary credentials through IAM roles.

Example

[ADMIN-account]
region = eu-central-1
role_arn = arn:aws:iam::ACCOUNT-ID:role/IAMRoleName
web_identity_token_file = /var/run/secrets/eks.amazonaws.com/serviceaccount/token

[DEV-account]
region = eu-central-1
role_arn = arn:aws:iam::ACCOUNT-ID:role/IAMRoleName
source_profile = ADMIN-account
role_session_name = komiser_session

Local Komiser CLI


Create an IAM user

Create an IAM user with the following IAM policy:

wget https://raw.githubusercontent.com/mlabouardy/komiser/master/policy.json

Add user credentials locally

Add your Access Key ID and Secret Access Key to ~/.aws/credentials using this format

[default]
aws_access_key_id = <access key id>
aws_secret_access_key = <secret access key>
region = <AWS region>

Run Komiser CLI

That should be it. Try out the following from your command prompt to start the server:

komiser start

Komiser CLI (Restricted regions)


There might be times when you would like to specifically restrict the scope of Komiser’s reach to a specific cloud region or a subset of them. This can be useful for organizations with tight SCPs in place. Add the --regions flag to the Komiser start command and seperate the regions with commas.

komiser start --regions eu-central-1,us-east-1,ap-southeast-1	

Note that all AWS Global resources in your account will be retrieved even using the --regions

EKS installation (single account)


Link to repository

We will be using the official Komiser Helm Chart to deploy Komiser to our EKS cluster.

Prerequisite

Helm installed locally

Create and IAM OIDC provider for your cluster

  1. Open the Amazon EKS.

  2. Select the name of your cluster.

  3. In the Details section on the Overview tab, note the value of the OpenID Connect provider URL.

  4. Open the IAM console at https://console.aws.amazon.com/iam/.

  5. In the left navigation pane, choose Identity Providers under Access management. If a Provider is listed that matches the URL for your cluster, then you already have a provider for your cluster. If a provider isn’t listed that matches the URL for your cluster, then you must create one.

  6. To create a provider, choose Add Provider.

  7. For Provider Type, choose OpenID Connect.

  8. For Provider URL, paste the OIDC issuer URL for your cluster, and then choose Get thumbprint.

  9. For Audience, enter sts.amazonaws.com and choose Add provider.

Create IAM role and attach a Komiser IAM policy

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the left navigation pane, choose Policies and then choose Create policy.

  3. Choose the JSON tab.

  4. In the Policy Document field, paste the Komiser recommended policy.

  5. Choose Review policy.

  6. Enter a name and description for your policy and then choose Create policy.

  7. Record the Amazon Resource Name (ARN) of the policy to use later when you create your role.

Create an IAM role for a service account

  1. Let’s generate the trust relationship policy. Copy the following code block to your computer.

    read -r -d '' TRUST_RELATIONSHIP <<EOF
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "arn:aws:iam::${ACCOUNT_ID}:oidc-provider/${OIDC_PROVIDER}"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "${OIDC_PROVIDER}:aud": "sts.amazonaws.com",
              "${OIDC_PROVIDER}:sub": "system:serviceaccount:${NAMESPACE}:komiser"
            }
          }
        }
      ]
    }
    EOF
    echo "${TRUST_RELATIONSHIP}" > trust.json
    
Make sure to substitute ${NAMESPACE} for the namespace you will deploy the helm chart in. If deployed in any other namespace, you will see sts:AssumeRoleWithWebIdentity failure messages in the pod logs.
  1. Run the modified code block from the previous step to create a file named trust.json.

  2. Run the following AWS CLI command to create the role. Replace my-iam-role with a name for your IAM role, and my-role-description with a description for your role.

    aws iam create-role --role-name my-iam-role --assume-role-policy-document file://trust.json --description "my-role-description"
    
  3. Run the following command to attach an IAM policy to your role. Replace my-iam-role with the name of your IAM role, 111122223333 with your account ID (or with aws, if you’re attaching an AWS managed policy), and my-iam-policy with the name of an existing policy that you created or an IAM AWS managed policy.

    aws iam attach-role-policy --role-name my-iam-role --policy-arn=arn:aws:iam::111122223333:policy/my-iam-policy
    

Update ServiceAccount

Update templates/service-account.yaml with the IAM role you’ve created previously

apiVersion: v1
kind: ServiceAccount
metadata:
  name: komiser
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME

Add custom values to config.toml file in configMap template

[[aws]]
name="NAME"
source="CREDENTIALS_FILE" // or use "ENVIRONMENT_VARIABLES"
path="path/to/credentials"
profile="default"

[sqlite]
file="komiser.db"

// or 
// [postgres]
// uri="postgres://postgres:komiser@localhost:5432/komiser?sslmode=disable"

Installing the chart

To install the chart:

$ helm install -f values.yaml komiser .

The above command deploys Komiser on the Kubernetes cluster in the default configuration.

Here’s a video tutorial on how to deploy Komiser to an EKS cluster:

Multiple Account EKS Installation


Below you will find the steps to deploy Komiser to an EKS cluster, such that it can monitor resources from multiple AWS accounts.

We are working with two AWS accounts here: ADMIN and DEV accounts.

Solution diagram:

Create an IAM OIDC provider for your cluster

  1. Open the Amazon EKS console.
  2. Select the name of your cluster.
  3. Once the cluster is up and running, note the value of the OpenID Connect provider URL from the Details section on the Overview tab.
  4. Open the AWS IAM console.
  5. In the left navigation pane, choose Identity Providers under Access management.

    If a Provider is listed that matches the URL for your cluster, then you already have a provider for your cluster. If a provider isn’t listed that matches the URL for your cluster, then you must create one.

  6. To create a provider, choose Add Provider.
  7. For Provider Type, choose OpenID Connect.
  8. For Provider URL, paste the OIDC issuer URL for your cluster, and then choose Get thumbprint.
  9. For Audience, enter sts.amazonaws.com and choose Add provider.

Register the ADMIN OIDC provider in the DEV Account

  1. Grab the OpenID Connect provider URL from the ADMIN account.
  2. Open the AWS IAM console in the DEV account.
  3. In the left navigation pane, choose Identity Providers under Access management.
  4. To create a provider, choose Add Provider.
  5. For Provider Type, choose OpenID Connect.
  6. For Provider URL, paste the ADMIN OIDC URL, and then choose Get thumbprint.
  7. For Audience, enter sts.amazonaws.com and choose Add provider.

Create an ADMIN IAM role for the ADMIN Account

  1. Create a the Admin IAM role using the same configuration as mentioned in the above section:
  2. Additionally modify the IAM policy to assume the DEV IAM role (once created):
{
    "Sid": "6",
	  "Effect": "Allow",
	  "Action": "sts:AssumeRole",
	  "Resource": "arn:aws:iam::${DEV_ACCOUNT_ID}:role/${DEV_IAM_ROLE}"
}

Create a DEV IAM role for the DEV Account

  1. Add the recommended Komiser policy
  2. Create a Trust Relationship with the ADMIN IAM role
{
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": {
                 "AWS": "${ADMIN_IAM_ROLE_ARN}"
             },
             "Action": "sts:AssumeRole",
             "Condition": {}
         }
     ]
 }

Helm Chart Configuration

We’ll be modifying the helm chart, to deploy Komiser to the EKS cluster.

Add the ADMIN role to the ServiceAccount

Add your values for ACCOUNT_ID and ROLE_Name

apiVersion: v1
kind: ServiceAccount
metadata:
  name: komiser
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME

Add a ConfigMap to the /templates folder

Add the configmap.yaml file the the /templates folder in the root of the repository:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-configmap
  annotations:
    meta.helm.sh/release-name: komiser
    meta.helm.sh/release-namespace: ${NAMESPACE}
  labels:
    app.kubernetes.io/managed-by: Helm
  namespace: ${NAMESPACE}
data:
 config.toml: |-
   [[aws]]
   name="Admin Account"
   source="CREDENTIALS_FILE"
   path="/path/to/credentials/file"
   profile="Admin-User" # Required if CREDENTIALS_FILE is set

   [[aws]]
   name="Dev Account"
   source="CREDENTIALS_FILE"
   path="/path/to/credentials/file"
   profile="Dev-User" # Required if CREDENTIALS_FILE is set

   [sqlite]
   file="komiser.db"

Mount the ConfigMap to the Deployment manifest

apiVersion: apps/v1 
kind: Deployment 
metadata: 
  name: komiser-deploy
spec:
  selector: 
    matchLabels: 
      app: komiser
  template: 
     metadata: 
      name: komiser
      labels: 
        app: komiser
     spec:
      serviceAccountName: komiser
      volumes:
      - name: test-volume
        configMap:
          name: aws-configmap
      containers: 
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          command: ["komiser","start","--config","/root/.aws/config.toml"]
          env:
          - name: AWS_DEFAULT_REGION
            value: "{{ .Values.aws.region }}"
          - name: AWS_CONFIG_FILE
            value: /root/.aws/credentials
          volumeMounts:
          - name: test-volume
            mountPath: /root/.aws/

Points to remember:

  1. Make sure not to change the mount path or internal volume path here. The paths should match the example above.
  2. The config.toml file will be mounted as a volume at the location: /root/.aws/. Therefore, make sure to provide the same path in the komiser start command for the container.
  3. Have a valid credentials file that the deployment has access to.

Here’s a video tutorial on how to deploy Komiser to an EKS cluster, with a Multi-Account Configuration: