> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# quali/cloudshell-colony

This orb integrates CloudShell Colony into your CI/CD pipeline. You can use the available build tasks to create a sandbox from any blueprint, start your tests and end the sandbox when finished. To use this orb you need to have an account in CloudShell Colony and API token The source code for this orb can be found here https://github.com/QualiNext/cloudshell-colony


## Commands

### end-sandbox

Stops CloudShell Colony sandbox environment


| Parameter | Type | Default | Description |
|---|---|---|---|
| `colony-token` | env_var_name | CS_COLONY_TOKEN | Name of environment variable containing Colony API Token
 |
| `colony-url` | env_var_name | CS_COLONY_SERVER | URL of Colony Server
 |
| `sandbox-id` | env_var_name | SANDBOX_ID | Environment variable with the ID of the sandbox
 |
| `space` | env_var_name | CS_COLONY_SPACE | Name of Colony space
 |

### start-sandbox

Launches CloudShell Colony Sandbox from a blueprint


| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifacts` | string | {} | String with the list of artifacts.
Json format {'key1': 'value1', ..., 'keyN': 'valueN'}
 |
| `blueprint` | string |  | Name of the blueprint used for creating a Colony sandbox.
 |
| `colony-token` | env_var_name | CS_COLONY_TOKEN | Name of environment variable containing Colony API Token
 |
| `colony-url` | env_var_name | CS_COLONY_SERVER | URL of Colony Server
 |
| `duration` | string | PT2H | Duration (ISO 8601), after which CloudShell Colony will stop the deployment
 |
| `inputs` | string | {} | String with the list of inputs.
Json format {'key1': 'value1', ..., 'keyN': 'valueN'}
 |
| `sandbox-details-variable` | string | SANDBOX_DETAILS | The name of environment variable which will be used to store full information about sandbox
 |
| `sandbox-id-variable` | string | SANDBOX_ID | The name of environment variable which will be used to store sandbox id
 |
| `sandbox-name` | string | circleci-orb-sandbox | Name of sandbox.
 |
| `space` | env_var_name | CS_COLONY_SPACE | Name of Colony space
 |
| `timeout` | integer | 30 | Timeout for this step in minutes. If the sandbox will not be ready when the timeout is reached, CloudShell Colony will abort the deployment
 |

## Jobs

### sandbox

Run your build scenario once sandbox environment is ready.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `artifacts` | string | {} | String with the list of artifacts.
Json format {'key1': 'value1', ..., 'keyN': 'valueN'}
 |
| `blueprint` | string |  | Name of the blueprint used for creating a Colony sandbox.
 |
| `colony-token` | env_var_name | CS_COLONY_TOKEN | Name of environment variable containing Colony API Token
 |
| `colony-url` | env_var_name | CS_COLONY_SERVER | URL of Colony Server
 |
| `image` | string | circleci/python | The name of image |
| `inputs` | string | {} | String with the list of inputs.
Json format {'key1': 'value1', ..., 'keyN': 'valueN'}
 |
| `sandbox-name` | string | circleci-orb-sandbox | Name of sandbox.
 |
| `space` | env_var_name | CS_COLONY_SPACE | Name of Colony space
 |
| `steps` | steps |  | Steps to execute once the Colony Sandbox is available |
| `tag` | string | latest | The image version tag |

## Executors

### default

The sample executor.
Any executor with curl pre-installed can be used instead


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image` | string | circleci/python | The name of image |
| `tag` | string | latest | The image version tag |

## Examples

### fetch-info

Start sandbox, echo its full description, stop sandbox


```yaml
jobs:
  build:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - colony/start-sandbox:
          artifacts: '{''app-frontend'':''latest/my-app.latest.tar.gz''}'
          blueprint: my-application
          inputs: '{''AWS_INSTANCE_TYPE'': ''m5.large''}'
          sandbox-name: test-sandbox
      - run:
          command: echo "Sandbox ID is ${SANDBOX_ID}"
          name: Fetch Details
      - colony/end-sandbox:
          sandbox-id: SANDBOX_ID
orbs:
  colony: quali/cloudshell-colony@1
version: 2.1
workflows:
  easy:
    jobs:
      - build
```

### test-app

This example demonstrates how you can build and test your app using Colony Orb.
First build app and publish it to s3 bucket. Than deploy CloudShell Colony Sandbox
with your new application as an artifact parameter and do some testing against the endpoint
of your deployed application.


```yaml
jobs:
  build-and-publish:
    docker:
      - image: circleci/ruby:2.4.1
    steps:
      - checkout
      - run:
          command: |
            mkdir -p workspace
            tar -zcf my-webapp.latest.tar.gz -C my_app/ .
          name: Archive app
      - aws-s3/copy:
          from: my-webapp.latest.tar.gz
          to: s3://my-webapp-artifacts/latest/
orbs:
  aws-s3: circleci/aws-s3@1.0.11
  colony: quali/cloudshell-colony@1.0
version: 2.1
workflows:
  leadeasy:
    jobs:
      - build-and-publish
      - colony/sandbox:
          artifacts: '{''webapp-frontend'':''latest/my-webapp.latest.tar.gz''}'
          blueprint: my-web-application
          inputs: '{''AWS_INSTANCE_TYPE'': ''m5.large''}'
          name: Test Application
          requires:
            - build-and-publish
          sandbox-name: test-sandbox
          steps:
            - run: echo "Do some testing here"
            - run:
                command: >
                  echo "Getting application endpoint"

                  SB_ENDPOINT="SB_${SANDBOX_ID}_SHORTCUT_1"

                  echo "Checking ${!SB_ENDPOINT}"

                  curl --write-out "%{http_code}\n" --silent --output /dev/null
                  "${!SB_ENDPOINT}"
```