Skip to content
This repository has been archived by the owner on Feb 5, 2021. It is now read-only.

Latest commit

 

History

History
545 lines (372 loc) · 15.6 KB

cli-reference.md

File metadata and controls

545 lines (372 loc) · 15.6 KB
Raw

Cellery CLI Commands

  • setup - create/manage cellery runtime installations.
  • init - initialize a cellery project.
  • build - build a cell image.
  • set namespace - set the targeted namespace.
  • run - create cell instance(s).
  • test - test cell instance(s).
  • view - view cell and component dependencies.
  • list - list information about cell instances/images.
  • delete - Delete cell images.
  • login - login to cell image repository.
  • push - push a built image to cell image repository.
  • pull - pull an image from cell image repository.
  • terminate - terminate a cell instance.
  • status - check status of cell instance.
  • logs - display logs of one/all components of a cell instance.
  • inspect - list the files included in a cell image.
  • extract-resources - extract packed resources in a cell image.
  • patch - perform a patch update on a particular cell instance.
  • route-traffic - route a percentage of traffic to a new cell instance.
  • export-policy - export a policy from cellery run time.
  • apply-policy - apply a policy to a cellery instance.

Cellery Setup

Cellery setup command install and manage cellery runtimes. For this purpose it supports several sub commands. Please refer the setup command readme for complete instructions.

Cellery setup status:

Display status of cluster with a status list of system components

Ex:

   cellery setup status

Back to Command List

Cellery Init

This will initialize a new cellery project in the current directory with the given name which includes an auto-generated cell definition. The project name also can be provided as inline param which will initialize the cellery project as given.

Ex:

   cellery init 
   cellery init my-first-project

Back to Command List

Cellery Build

Build an immutable cell image.

Parameters:
  • Cell file: The .bal which has the cell definition
  • Cell image name: This is the image name, and it should be in format <ORGANIZATION_NAME>/<IMAGE_NAME>:<VERSION>

Ex:

   cellery build my-project.bal wso2/my-cell:1.0.0

Back to Command List

Cellery Set Namespace

Set the targeted namespace of the Cellery runtime. Thereafter, all CLI operations will be done upon that particular namespace.

Parameters:
  • Namespace : targeted namespace

Ex:

   cellery set namespace test

Back to Command List

Cellery Run

Create a running instance from a cell image.

Parameters:
  • Cell image name: name of a built Cell image
Flags (Optional):
  • -y, --assume-yes : Flag to enable/disable prompting for confirmation before starting instance(s)
  • -e, --env : Set an environment variable for the cellery run method in the Cell file
  • -l, --link : Link an instance with a dependency alias
  • -n, --name : Name of the cell instance
  • -s, --share-instances : Share all instances among equivalent Cell Instances
  • -d, --start-dependencies : Start all the dependencies of this Cell Image in order

Ex:

   cellery run wso2/my-cell:1.0.0
   cellery run wso2/my-cell:1.0.0 -n my-cell-inst 
   cellery run wso2/my-cell:1.0.0 -l dependencyKey:dependentInstance
   cellery run wso2/my-cell:1.0.0 -e config=value 
   cellery run wso2/my-cell:1.0.0 -d 
   cellery run wso2/my-cell:1.0.0 -s -d
   cellery run wso2/my-cell:1.0.0 -y

Back to Command List

Cellery Test

Test a cell instance

Parameters:
  • Cell image name: name of a built Cell image
Flags (Optional):
  • -y, --assume-yes : Flag to enable/disable prompting for confirmation before starting instance(s)
  • -e, --env : Set an environment variable for the cellery run method in the Cell file
  • -l, --link : Link an instance with a dependency alias
  • -n, --name : Name of the cell instance
  • -s, --share-instances : Share all instances among equivalent Cell Instances
  • -d, --start-dependencies : Start all the dependencies of this Cell Image in order
  • --debug : Enable test debug mode
  • -p, --project-location Ballerina Project location

Ex:

   cellery test wso2/my-cell:1.0.0
   cellery test wso2/my-cell:1.0.0 -n my-cell-inst 
   cellery test wso2/my-cell:1.0.0 -l dependencyKey:dependentInstance
   cellery test wso2/my-cell:1.0.0 -e config=value 
   cellery test wso2/my-cell:1.0.0 -d 
   cellery test wso2/my-cell:1.0.0 -s -d
   cellery test wso2/my-cell:1.0.0 --debug -p foo_proj -y

Back to Command List

Cellery View

View the cell image with inter component dependencies, and inter cell dependencies.

   cellery view wso2/my-cell:1.0.0

Back to Command List

Cellery List

List running instances/cell images. This command can take four forms, for listing components, images, ingresses or instances.

Cellery List Components:

List the components which the cell image/instance encapsulate.

Parameters:
  • cell instance name/cell image name: Either the cell instance name and cell image name.

Ex:

  cellery list components my-cell-inst
  cellery list components cellery-samples/employee:1.0.0
Cellery List Images

Lists the available cell images.

Ex:

  cellery list images
Cellery List Ingresses

List the exposed APIs of a cell image/instance.

Parameters:
  • cell instance name/cell image name: Either the cell instance name and cell image name.

Ex:

  cellery list ingresses my-cell-inst
  cellery list ingresses cellery-samples/employee:1.0.0
Cellery List Instances

List all running cells.

Ex:

   cellery list instances

Back to Command List

Cellery List dependencies

List the dependency information for a given cell instance. The dependency cell image, version and the cell instance name will be provided as the output.

Parameters:
  • cell instance name: A valid cell instance name.

Ex:

   cellery list dependencies my-cell-inst

Back to Command List

Cellery delete

Delete cell images. This command will delete one or more cell images from cellery local repository. Users can also delete all cell images by executing the command with "--all" flag.

Parameters:
  • cell image names: This is a space separated list of existing cell images and/or regular expression of cell images.

Ex:

  cellery delete cellery-samples/employee:1.0.0 cellery-samples/hr:1.0.0
  cellery delete --regex 'cellery-samples/.*:1.0.0'
  cellery delete cellery-samples/employee:1.0.0 --regex '.*/employee:.*'
  cellery delete --all

Back to Command List

Cellery login

Log in the user to the cellery image repository, which is docker hub, and caches the credentials in the key ring in their machine, therefore user doesn't need to repeat typing the credentials.

Ex:

   cellery login

Back to Command List

Cellery Push

Push the cell image to the docker hub user account.

Parameters:
  • cell image name: This is the image name, and it should be in format <ORGANIZATION_NAME>/<IMAGE_NAME>:<VERSION>

Ex:

   cellery push wso2/my-cell:1.0.0

Back to Command List

Cellery Pull

Pull the cell image from docker registry and include in the cellery local repository.

Parameters:
  • cell image name: This is the image name, and it should be in format <ORGANIZATION_NAME>/<IMAGE_NAME>:<VERSION>

Ex:

  cellery pull wso2/my-cell:1.0.0

Back to Command List

Cellery Terminate

Terminate running cell instances within cell runtime.

Parameters:
  • cell instance names: Names of the instances running in the cellery system

Ex:

  cellery terminate employee
  cellery terminate pet-fe pet-be
  cellery terminate --all

Back to Command List

Cellery Status

Check for the runtime status of the cell instance.

Parameters:
  • cell instance name: Name of the instance running in the cellery system

Ex:

  cellery status my-cell-inst

Back to Command List

Cellery Logs

Fetch logs of all components or specific component within the cell instance and print in the console.

Parameters:
  • cell instance name: Name of the instance running in the cellery system
Flags (Optional):
  • -c, --component: Name of the component of which the logs are required

Ex:

  cellery logs my-cell-inst 
  cellery logs my-cell-inst -c my-comp

Back to Command List

Cellery Inspect

List the files included in a cell image.

Parameters:
  • cell image name: This is the image name, and it should be in format <ORGANIZATION_NAME>/<IMAGE_NAME>:<VERSION>

Ex:

  cellery inspect wso2/my-cell:1.0.0

Back to Command List

Cellery Extract Resources

This will extract the resources folder of the cell image. This is useful to see the swagger definitions of the cell APIs therefore users can generate client code to invoke the cell APIs.

Parameters:
  • cell image name: This is the image name, and it should be in format <ORGANIZATION_NAME>/<IMAGE_NAME>:<VERSION>
Flags (Optional):
  • -o, --output: The directory into which the resources should be extracted

Ex:

  cellery extract-resources wso2/my-cell:1.0.0 
  cellery extract-resources wso2/my-cell:1.0.0 -o /my/output/resource

Back to Command List

Cellery Patch

Perform a patch update on a running cell instance, targeting a particular component. This is done as a rolling update, hence only changes to docker images encapsulated within components will be applied.

Parameters:
  • cell instance name: The name of a running cell instance, which should be patched.
  • target component name: The name of the component of the running instance to patch.
Flags (Mandatory):
  • -i, --container-image: container image name which will be used to update the target component. Only applicable when a target component is specified.
Flags (Optional):
  • -e, --env: environment variable name value pairs separated by a '=' sign. Only applicable when a target component is specified.

Ex:

  cellery update myhello controller --container-image mycellorg/hellocell:1.0.0
  cellery update myhello controller --container-image mycellorg/hellocell:1.0.0 --env foo=bar --env name=alice

Back to Command List

Cellery Route Traffic

This is used to direct a percentage of traffic originating from one cell instance to another. This command is used in advanced deployment patterns such as Blue-Green and Canary.

Flags (Mandatory):
  • -d, --dependency: Existing dependency instance, which is currently receiving traffic from the relevant source instance(s).
  • -t, --target: The new target instance to which traffic should be routed to.
Flags (Optional):
  • -s, --source: The source instance which is generating traffic for the dependency instance specified in the Parameters above. If this is not given all instances which are currently depending on the provided dependency instance will be considered.
  • -p, --percentage: The percentage of traffic to be routed to the target instance. If not specified, this will be considered to be 100%.
  • -a, --enable-session-awareness: Flag to enable session aware routing based on user name. An instance will be selected and will be propagated via the header x-instance-id. Its the cell component's responsibility to forward this header if this option is to be used.
  • -y, --assume-yes: Assume the answer as yes to any user prompts, such as the confirmation to continue with routing when there are api version mismatches.

Ex:

  cellery route-traffic --source hr-client-inst1 --dependency hr-inst-1 --target hr-inst-2 --percentage 20 
  cellery route-traffic --dependency hr-inst-1 --target hr-inst-2 --percentage 20
  cellery route-traffic --dependency hr-inst-1 --target hr-inst-2 --percentage 20 --enable-session-awareness
  cellery route-traffic --dependency hr-inst-1 --target hr-inst-2
  cellery route-traffic --dependency hr-inst-1 --target hr-inst-2 --assume-yes

Back to Command List

Cellery Export Policy

Export a policy from the Cellery runtime as a file system artifact. This can be either exported to a file specified by the CLI user, or a file starting with cell instance name.

Cellery Export Policy Autoscale:

Export a set of autoscale policies which is applicable to a given cell instance.

Parameters:
  • instance type: Whether the instance is a composite or a cell, denoted by either 'composite' or 'cell'.
  • cell instance name: A valid cell instance name.
Flags (Optional):
  • -f, --file: File name to which the autoscale policy should be exported.

Ex:

  cellery export-policy autoscale cell mytestcell1 -f myscalepolicy.yaml
  cellery export-policy autoscale composite mytestcell1

Back to Command List

Cellery Apply Policy

Apply a policy/set of policies included in a file to the Cellery runtime targeting a running cell instance.

Cellery Apply Policy Autoscale:

Apply a file containing a set of autoscale policies or zero-scale policies to the given cell instance.

Parameters:
  • instance type: Whether the instance is a composite or a cell, denoted by either 'composite' or 'cell'.
  • instance name: The target instance to which the autoscale policies should be applied.
  • autoscale policy file: A file containing a valid autoscale policy/set of autoscale policies.

Ex:

  cellery apply-policy autoscale cell myinstance myscalepolicy.yaml
  cellery apply-policy autoscale composite myinstance myscalepolicy.yaml
Sample autoscale policy:
components:
- name: controller
  scalingPolicy:
    hpa:
      maxReplicas: 5
      metrics:
      - resource:
          name: cpu
          targetAverageUtilization: 50
        type: Resource
      minReplicas: 1
- name: catalog
  scalingPolicy:
    replicas: 1
- name: orders
  scalingPolicy:
    replicas: 1
- name: customers
  scalingPolicy:
    hpa:
      minReplicas: 1
      maxReplicas: 3
      metrics:
      - resource:
          name: memory
          targetAverageValue: "64Mi"
        type: Resource
gateway:
  scalingPolicy:
    replicas: 1
Sample zero-scale policy:
components:
- name: controller
  scalingPolicy:
    kpa:
      maxReplicas: 5
      concurrency: 2
- name: catalog
  scalingPolicy:
    replicas: 1
- name: orders
  scalingPolicy:
    replicas: 1
- name: customers
  scalingPolicy:
    hpa:
      maxReplicas: 3
      metrics:
      - resource:
          name: memory
          targetAverageValue: 64Mi
        type: Resource
- name: portal
gateway: 
  scalingPolicy:
        replicas: 1
  • The flag 'overridable' implies whether the existing policy can be overriden by the same command repeatedly.

Back to Command List