V Cloud

Configure VKubefile

Introduction

  1. VKubefile.yaml is a YAML configuration file for container deployment. It provides a straightforward way to define container building, deployment, and runtime parameters.
  2. The ~/.vkube/config.yaml file is used to store login information. When configuring the values for DockerhubToken or GHCRToken, it's important to ensure that the permissions are set to read and write. Otherwise, pushing images will fail.

Basic Configuration

Kind: vkube                    # Required, currently only supports vkube
vkubeToken: "your-token"           # Required, it's the token you can get it from the vkube website
imageRegistry: "docker"       # Required, registry type, supports "docker" or "ghcr"

Container Configuration

Configure one or more containers under the containers field:

containers:
  - deploy:                   # Required, deployment configuration
      containerName: "app1"   # Container name, must be lowercase letters, numbers, may include hyphens
      resourceUnit: 1         # Resource units, must be integer >= 1,and can not greater than the total resourceUnit of the service which you buy in VKube website
      ports:                  # Optional, port mapping
        - containerPort: 8080 # Container port (1-65535)
          hostPort: 8080      # Host port (1-65535)
          path: /
          rewrite: false
      env:                    # Optional, environment variables
        - name: "DB_HOST"
          value: "localhost"
      configurations:         # Optional, configuration file mapping
        "./config/app.conf": "/etc/app/config.conf"  # Local path: Container mount path

    # Image configuration, you can only choose one method in one container
    
    # Method 1: Use existing image
    registryImagePath: "docker.io/nginx:latest"    # Complete image path
    
    # Method 2: Build image locally
    build:
      installSSH: false
      sshPubKeyPath: "~/.ssh/id_rsa.pub"
      dockerfilePath: "./Dockerfile"    # Dockerfile path
      contextPath: "."                  # Optional, build context
      buildArgs:                        # Optional, build arguments
        - name: VERSION
          value: "1.0"
    imageName: "myapp"                  # Image name
    tag: "v1.0"                         # Image tag

Configuration Details

Image Configuration

Two methods supported:

  1. Using registryImagePath for existing images

    • Supported formats:
      • docker.io/account/image-name:tag
      • ghcr.io/account/image-name:tag
      • image-name:tag (Docker Hub)
      • account/image-name:tag (Docker Hub)

  2. Local image build

    • Requires build.dockerfilePath
    • Must provide both imageName and tag
    • Optional contextPath and buildArgs
    • Optional installSSH and sshPubKeyPath

Deployment Configuration

  • containerName: Container name, must follow Kubernetes naming conventions
  • resourceUnit: Resource unit configuration, integer value
  • ports: Port mapping from container to host
  • env: Environment variables
  • configurations: Configuration file mapping
  • persistStorage: Optional persistent storage path
  • command: Optional container command override
  • args: Optional command arguments

SSH Configuration

  1. Set Ports: Set containerPort value to 22, and set hostPort value to any right value.

  2. Set installSSH value to true, and configure the sshPubKeyPath. You must ensure that the dockerFilePath is right. Then using the vkube deploy -f ./xxxfile to deploy the service.

  3. To connect ssh, you can use the command ssh -p xxxhostPort root@xxxServerIP

Example configuration:

Kind: vkube
vkubeToken: "xxx"
imageRegistry: docker
containers:
- imageName: nginx
  tag: ""
  deploy:
    containerName: nodewatcher
    resourceUnit: 1
    command: ["/kube/v-cloud-kube", "-file","/config/v-kube-service.yaml","-permission-list","/config/permission_list.yaml"]
    ports: 
    - containerPort: 22 
      hostPort: 20001
    env:
    - name: ENV1
      value: VALUE1
    - name: ENV2
      value: VALUE2
    args:
    - "config.file=/etc/loki/loki-config.yaml"
    - "config.expand-env=true"
    configurations:
      /local-path1/config-name1: "/etc/nginx/conf.d/default.conf"
      /local-path2/config-name2: "/etc/nginx/conf.d/default.conf"
    persistStorage: "/test"
  build:
    installSSH: true
    sshPubKeyPath: "~/.ssh/id_rsa.pub"
    dockerfilePath: "./Dockerfile"    # Dockerfile path
    contextPath: "."                  # Optional, build context
    buildArgs:
      - name: GOLANG_VER
        value: 1.22.3
      - name: port
        value: 3005

Example

need to build image and deploy

Kind: vkube
vkubeToken: "your-token"
imageRegistry: "docker"
containers:
  - deploy:
      containerName: "web-app"
      resourceUnit: 2
      ports:
        - containerPort: 80
          hostPort: 8080
      env:
        - name: "ENV"
          value: "production"
      configurations:
        "./nginx.conf": "/etc/nginx/nginx.conf"
      persistStorage: "/data"
    build:
      dockerfilePath: "./Dockerfile"
      contextPath: "."
      buildArgs:
        - name: VERSION
          value: "1.0"
    imageName: "web-app"
    tag: "v1.0"

existed image in remote registry and only need to deploy

Kind: vkube
vkubeToken: "xxx"
imageRegistry: docker
containers:
- registryImagePath: ghcr.io/vcloud-systems/v-node-watcher:v2.0
  deploy:
    containerName: nodewatcher
    resourceUnit: 4
    command: ["/kube/v-cloud-kube", "-file","/config/v-kube-service.yaml","-permission-list","/config/permission_list.yaml"]
    ports:
    - containerPort: 980
      hostPort: 20001
    env:
    - name: ENV1
      value: VALUE1
    - name: ENV2
      value: VALUE2
    args:
    - "config.file=/etc/loki/loki-config.yaml"
    - "config.expand-env=true"
    configurations:
      /local-path1/config-name1: "/etc/nginx/conf.d/default.conf"
      /local-path2/config-name2: "/etc/nginx/conf.d/default.conf"
    persistStorage: "/test"

Mixed

Kind: vkube
vkubeToken: "xxx"
imageRegistry: docker
containers:
- registryImagePath: ghcr.io/you-github-username/imagename:tag
  deploy:
    containerName: nodewatcher
    resourceUnit: 4
    command: ["/kube/v-cloud-kube", "-file","/config/v-kube-service.yaml","-permission-list","/config/permission_list.yaml"]
    ports:
    - containerPort: 980
      hostPort: 20001
    env:
    - name: ENV1
      value: VALUE1
    - name: ENV2
      value: VALUE2
    args:
    - "config.file=/etc/loki/loki-config.yaml"
    - "config.expand-env=true"
    configurations:
      /local-path1/config-name1: "/etc/nginx/conf.d/default.conf"
      /local-path2/config-name2: "/etc/nginx/conf.d/default.conf"
    persistStorage: "/test"
- imageName: nginx
  tag: ""
  deploy:
    containerName: nodewatcher
    resourceUnit: 1
    command: ["/kube/v-cloud-kube", "-file","/config/v-kube-service.yaml","-permission-list","/config/permission_list.yaml"]
    ports: 
    - containerPort: 980 
      hostPort: 20001
    env:
    - name: ENV1
      value: VALUE1
    - name: ENV2
      value: VALUE2
    args:
    - "config.file=/etc/loki/loki-config.yaml"
    - "config.expand-env=true"
    configurations:
      /local-path1/config-name1: "/etc/nginx/conf.d/default.conf"
      /local-path2/config-name2: "/etc/nginx/conf.d/default.conf"
    persistStorage: "/test"
  build:
    installSSH: false
    sshPubKeyPath: "~/.ssh/id_rsa.pub"
    dockerfilePath: "./Dockerfile"    # Dockerfile path
    contextPath: "."                  # Optional, build context
    buildArgs:
      - name: GOLANG_VER
        value: 1.22.3
      - name: port
        value: 3005

Important Notes

  1. registryImagePath and build configurations are mutually exclusive
  2. When using build, both imageName and tag are required
  3. Port numbers must be between 1-65535
  4. Configuration file paths must use valid filesystem path formats
  5. Resource units must be at least 1
  6. Container names must follow Kubernetes naming conventions
Last Updated: 9/16/2025, 7:02:30 AM

← Use Git Actions workflows to deploy →