Knts manifestation file reference

This guide walks you through the creation of a knts manifestation file.

What is knts manifestation file

The knts manifestation file is a configuration file that contains the instructions for knts CLI. Knts manifestation file is generally divided into 6 sections, 4 of which are main sections. Some are optional and others are required fields to create your knts manifestation file.

Sample knts file

YAML

name: sample-application

 build:
   frontend:
     context: src/frontend
     dockerfile: Dockerfile
     image: frontend:v0.8.0

deploy:
  - 'helm upgrade --install sample chart '

dev:
  frontend:
    image: frontend
    command: bash
    workdir: /app
    sync:
      - src/frontend:/app   
    forward:
      - 7070:7070    

This is the list of sections that manifestation files contain.

• Name (Auto-generated, Required)
• Build (Auto-generated, Optional)
• Context (Optional)
• Deploy (Auto-generated, Required)
• Destroy (Optional)
• Dev (Required, Generated under comment)

Let's deep-dive into each section of the manifestation file, and know what needs to be configured for the knts CLI to run smoothly.

Name (Auto-generated, Required)

This section/field in the manifestation file contains the name of the created dev environment. This is an auto-generated field which is generally your git repository name.

This field value can be changed according to your requirements.

YAML

name: microservices-demo

Build (Auto-generated, Optional)

The build section contains the information about your docker build configuration. This is an Optional field to configure. You can ignore or remove this section if you don't want to run the build process.

You can configure multiple Images in a single section as shown below.

YAML

 build:

   frontend:
     context: src/frontend
     dockerfile: Dockerfile
     image: frontend:v0.8.0

   backend:
     context: src/backend
     dockerfile: Dockerfile
     image: backend:v0.8.0

   db:
     context: src/db
     dockerfile: Dockerfile
     image: db:v0.8.0

The options for each list of images are as follows

• args(Optional) - Arguments that you need to provide with Docker build
• cache_from(Optional) - Any cache that is stored before for further use of the build process
• context(Required) - The path for the Docker file.
• depends_on(Optional) - Any dependencies for the Docker build to run.
• dockerfile(Required) - Name of the Docker file
• export_cache (Optional) - This option lets you export the cache of the build process
• image(Required) - Name of the image
• secrets (Optional) - This field is required when using a private repository.
• target (Optional) - The path where the image needs to be stored.

Context (Optional)

This section contains the context of configuring the deployment or dev container. When not configured in the yaml file, by default, it uses the current context that is set in the terminal with knts context. It can be configured as below.

YAML

context: default

Deploy (Auto-generated, Required)

The deploy session is where you can configure the set of commands, that are used when deploying your container. Deploy allows you to give a list of commands which can be executed in an order.

Examples

A few examples regarding the format of writing a deploy secession are as follows.

Deploy with Helm (Recommended)

When using a helm chart to deploy your application you can directly list the commands as shown below.

YAML

deploy:
  - 'helm upgrade --install my-application chart '

This session can also be configured as below

YAML

deploy:
  commands:
    - 'helm upgrade --install my-application chart '

If you want to name the set of commands, you can also configure as follows

YAML

deploy:
  - name: Deploying the workload 
    command: 'helm upgrade --install my-application chart '

As this is a list format, you can list multiple commands.

Deploy with Docker compose

When deploying a docker-compose application, you can directly mention the file name as shown below.

YAML

deploy:
  compose: docker-compose.yml

Destroy (Optional)

By default, the knts destroy command destroys everything present in the deploy section.

The destroy session is where you can configure the set of commands, that are used when destroying your container. You can use this section when you have other resources that must be destroyed along with your deployments.

Examples

A few examples regarding the format of writing a destroy secession are as follows.

Destroy with Helm

When using a helm chart to deploy your application, you had a pre-installed dependency helm chart that should also be destroyed during distortion. you can use this section to mention the commands to delete the dependency resources.

YAML

destroy:
  - 'helm uninstall dependency-chat'

This session can also be configured as below

YAML

destroy:
  commands:
    - 'helm uninstall dependency-chat '

If you want to name the set of commands, you can also configure as follows

YAML

destroy:
  - name: Destroying the workload 
    command: 'helm uninstall dependency-chat '

As this is a list format, you can list multiple commands.

Dev (Required, Generated under comment)

This is the main section of knts manifestation where you can configure all the desired requirements of your service that is deployed in the cluster. Here you can configure env, port, base image, resource allocation, security context, folder details to be synced, and so on.

A sample dev section looks like this

YAML

dev:
  frontend:
    image: node18
    command: bash
    workdir: /app
    sync:
      - src/frontend:/app   
    forward:
      - 7070:7070  

The options that can be configured are as follows.

affinity (optional)

If you have a multi-node cluster and want to deploy the application on a particular pod, that's when you use the affinity option. it is configured as follows:

YAML

dev:
  frontend:
    <----other requred fields---->
     affinity:
        podAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchExpressions:
                  - key: role
                    operator: In
                    values:
                      - web-server
              topologyKey: kubernetes.io/hostname

For more information about the affinity, refer to the documentation links.

autocreate (bool, optional)

When knts-upcommand doesn't have a deployment command into the cluster or it couldn't find any deployment in the cluster, this option (if set to true) will auto-create the deployment for the particular service. By default, this option is set to false. It can be configured as follows.

YAML

dev:
  frontend:
    <----other requred fields---->
     autocreate: true

Note: This option doesn't deploy the dependency services, it deploys only the current service that is selected when creating the dev container.

command (string, optional)

The commands configured in this option will be executed when creating the dev container. This is an optional field, you can manually run the commands when the container is up if you didn't configure any command here. if empty, the container will execute the sh command. This option is configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->
     command: bundle exec thin -p 3000

container (string, optional)

If you have multiple containers in the deployment, you can use this option to declare which container the dev container should enter. If not configured, it would take the first container. It can be configured as follows.

YAML

dev:
  frontend:
    <----other requred fields---->
     container: frontend

environment ([string], optional)

You can configure the environment variables to run the service here. It can be configured as follows.

YAML

dev:
  frontend:
    <----other requred fields---->
    environment:
      environment: development
      name: frontend
      DBPASSWORD:dbpassword

For more information about the environment variables, refer to the documentation links.

envFiles ([string], optional)

If you have a file that contains environment variables, you can attach them to the service with this option.

YAML

dev:
  frontend:
    <----other requred fields---->
    envFiles:
      - .env1
      - .env2

forward ([string], optional)

This option lets you declare the port of the service to port-forward. This can be configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->
  forward:
    - 8080:80

image (string, optional)

This option lets you declare the image on which the dev container should run. It can be declared as follows

YAML

dev:
  frontend:
    image: node18
    <----other requred fields---->

metadata (object, optional)

You can configure the annotations and service labels through this metadata option. This can be configured as follows

YAML

metadata:
  annotations:
    key1 : "value1",
  labels:
    key1 : "value

For more information about the labels, refer to the documentation links. For more information about the annotations, refer to the documentation links

persistentVolume (object, optional)

This option allows you to configure the persistent volumes for the knts dev container. The fields permitted to configure are as follows.

• enable: The dev container creates the persistent volume only when it is set to true. By default, it is true
• storageClass: The storage class that is used for the creation of persistent volume. By default, it would take the default storage class.
• size: The size of the persistent volume. By default, it would be 2Gi. You can increase or decrease the size according to the service you are using.

This can be configured as follows.

YAML

dev:
  frontend:
    <----other requred fields---->
    persistentVolume:
      enabled: true
      storageClass: standard
      size: 10Gi

Note:

• persistentVolume.enabled must be true if you use volumes.
• persistentVolume.enabled must be true if you want to share command history across development containers while developing an app.

resources (object, optional)

With this option, you can configure the resource allocation of the pod. it is configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->
    resources:
      requests:
        cpu: "250m"
        memory: "2Gi"
      limits:
        cpu: "500m"
        memory: "3Gi" 

For more information about the resource, refer to the documentation links.

reverse ([string], optional)

This option lets you reverse forward your application. This can be configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->
    reverse:
      - 8080:80

securityContext (object, optional)

This option allows you to configure the pod's security context. It can be configured as below

YAML

dev:
  frontend:
    <----other requred fields---->    
    securityContext:
      runAsUser: 1000
      allowPrivilegeEscalation: false
      capabilities:
        add:
          - SYS_PTRACE
      runAsNonRoot: true         
      runAsGroup: 1000
      fsGroup: 1000  

For more information about the security context, refer to the documentation links.

selector (map[string]string, optional)

This option allows you to configure the label selectors for the dev container. This can be configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->  
    selector:
      app.kubernetes.io/name: frontend

For more information about the selectors, refer to the documentation links.

serviceAccount (string, optional)

This option allows you to define the service account name. This can be configured as follows.

YAML

dev:
  frontend:
    <----other requred fields---->  
    serviceAccount: default

For more information about the affinity, refer to the documentation links.

sync ([string], required)

The Sync option allows the knts CLI to sync the local source code to the dev container created. This can be configured as the /folder/name/in/local/source/code:/work/directory/in/container, as follows.

YAML

dev:
  frontend:
    <----other requred fields---->  
    sync:
      - local/sour/code:/workdir

volumes ([string], optional)

This option lets you configure the list of paths in your dev container that you want to associate with persistent volumes. This is useful for storing the information between knts up executions, like downloaded libraries or cache information. A few ways it can be stored are as follows

For language packages

If you have any packages that need to be installed and stored in the dev container you can configure them as follows, this example shows for a Go language application.

YAML

dev:
  frontend:
    <----other requred fields---->  
    volumes:
      - /go/pkg/
      - /root/.cache/go-build/

For the database storage

If you have any tables that need to be stored in the dev container you can configure them as follows, this example shows for a mysql Configuration

YAML

dev:
  frontend:
    <----other requred fields---->  
    volumes:
      - data:/var/lib/mysql

workdir (string, optional)

This Option lets you set the working directory of the dev container. It is configured as follows

YAML

dev:
  frontend:
    <----other requred fields---->  
    workdir: /app    

Examples

Configuring a single application

If your git repository consists of a single service you can configure your dev section as follows

YAML

dev:  
  frontend:
    image: golang
    command: bash
    workdir: /src
    sync:
      - src/frontend:/src
    securityContext:
      runAsUser: 1000
      allowPrivilegeEscalation: false
      capabilities:
        add:
          - SYS_PTRACE
      runAsNonRoot: true      
      runAsGroup: 1000
      fsGroup: 1000      
    environment:
      - PORT=8080
      - ENVIRONMENT="dev"
    forward:
      - 8080:8080
    volumes:
      - /go/pkg/
      - /.cache/
    resources:
      requests:
        cpu: "250m"
        memory: "2Gi"
      limits:
        cpu: "500m"
        memory: "3Gi"

Configuring a multi-service application

If you have multiple services in one git repository, you can configure the dev section as follows

YAML

dev:
  frontend:
    image: golang
    command: bash
    workdir: /src
    sync:
      - src/frontend:/src
    securityContext:
      runAsUser: 1000
      allowPrivilegeEscalation: false
      capabilities:
        add:
          - SYS_PTRACE
      runAsNonRoot: true      
      runAsGroup: 1000
      fsGroup: 1000      
    environment:
      - PORT=8080 
      - ENVIRONMENT="dev"
    forward:
      - 8080:8080
    volumes:
      - /go/pkg/
      - /.cache/
    resources:
      requests:
        cpu: "250m"
        memory: "2Gi"
      limits:
        cpu: "500m"
        memory: "3Gi"
  currencyservice:
    image: node
    command: bash
    workdir: /app
    sync:
      - src/currencyservice:/app
    securityContext:
      runAsUser: 1000
      allowPrivilegeEscalation: false
      capabilities:
        add:
          - SYS_PTRACE
      runAsNonRoot: true         
      runAsGroup: 1000
      fsGroup: 1000       
    environment: 
      - PORT=7000
      - PROJECT_ID=klusternetes
    forward:
      - 7000:7000
    resources:
      requests:
        cpu: "250m"
        memory: "2Gi"
      limits:
        cpu: "500m"
        memory: "3Gi"

The name of the service in the deployment file should match the name of the service in the Dev session so that they can communicate and create a new container.