Metadata-Version: 2.1
Name: vgs-cli
Version: 0.1.0
Summary: VGS Client
Home-page: https://github.com/verygoodsecurity/vgs-cli
Author: Very Good Security
Author-email: dev@verygoodsecurity.com
License: BSD
Platform: any
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
Provides-Extra: tests
Requires-Dist: pyaml (==17.12.1)
Requires-Dist: PyYAML (==3.12)
Requires-Dist: simple-rest-client (==0.5.2)
Requires-Dist: requests (==2.13.0)
Requires-Dist: PyJWT (==1.5.3)
Provides-Extra: tests

# VGS Client
A command line tool that configures routes in VGS vaults
# Requirements
- Python 3.6
# Installation
To install the latest version enter
```
pip install vgs-cli
```
# Authentication
All commands provided by vgs-cli require authentication. Authentication is done using dashboard credentials (username/password + MFA).
To authenticate type
```
vgs authenticate
```
Your credentials are short-lived. If you come across a 'Credentials are expired' error, pls re-authenticate.
# Commands
## Parameters
| Name                                    | Description                                                                   | Mandatory                                | Default value                        |
| --------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------- |
| `tenant`                                | Tenant identifier of a vault                                                  | Yes                                    |                                        |
| `environment`                           | VGS environment. Possible values are `sandbox` and `live`                     | No                                     | sandbox                                |
## dump-all
This command dumps routes in a readable YAML format to stdout. We recommend redirecting output to a file for convenience.
```
vgs --tenant=tnteipi8liw --environment=sandbox route --dump-all
```
### Recommended way of using the command
```
vgs --tenant=tnteipi8liw --environment=sandbox route --dump-all > tnteipi8liw.yml
```
### Sample output looks like
```yaml
data:
- attributes:
    created_at: '2018-07-17T16:50:37'
    destination_override_endpoint: https://httpbin.verygoodsecurity.io
    entries:
    - classifiers: {}
      config:
        condition: AND
        expression: null
        rules:
        - condition: null
          expression:
            field: PathInfo
            operator: equals
            type: string
            values: [/post]
          rules: null
        - condition: null
          expression:
            field: ContentType
            operator: equals
            type: string
            values: [application/json]
          rules: []
      id: a46b73e5-df5a-4780-bc01-9e19b1aa04bc
      id_selector: null
      operation: REDACT
      operations: null
      phase: REQUEST
      public_token_generator: UUID
      targets: [body]
      token_manager: PERSISTENT
      transformer: JSON_PATH
      transformer_config: [$.secret]
    host_endpoint: (.*)\.verygoodproxy\.com
    id: 6153b3fc-f869-4fdd-824f-5ed6b1e393c5
    port: 443
    protocol: http
    source_endpoint: '*'
    updated_at: '2018-07-17T16:50:50'
  id: 6153b3fc-f869-4fdd-824f-5ed6b1e393c5
  type: rule_chain
- attributes:
    created_at: '2018-07-17T16:53:01'
    destination_override_endpoint: '*'
    entries: []
    host_endpoint: (.*)
    id: d6c86a9f-c85c-4ced-9998-16b050541f84
    port: 443
    protocol: http
    source_endpoint: '*'
    updated_at: '2018-07-17T16:53:01'
  id: d6c86a9f-c85c-4ced-9998-16b050541f84
  type: rule_chain
version: 1
```
## sync-all
This command synchronizes updates to routes back upstream. It takes a YAML document with routes via stdin.
### Important
For this command to work the following conditions should hold
- YAML document should be a result of a previous output from `dump-all`.
- You can only make changes to the entities in the original YAML document, and you must keep ids as is.
```
vgs --tenant=tnteipi8liw --environment=sandbox route --sync-all < tnteipi8liw.yml
```
## create-all
This command creates new routes in a vault. An input YAML document should take the same form as an output of the `dump-all` command.
A typical use case for this command is a migration of routes from a sandbox environment to live
```
vgs --tenant=tnt3lmevlos --environment=live route --create-all < tnteipi8liw.yml
```
# Typical scenarios
## Migrate routes from a sandbox environment to live
- Sandbox tenant: `tnt_sandbox`
- Live tenant: `tnt_live`
1. Dump routes from a sandbox vault locally
```
vgs --tenant=tnt_sandbox --environment=sandbox route --dump-all > tnt_sandbox.yml
```
2. Re-create routes in a live vault
```
vgs --tenant=tnt_live --environment=live route --create-all < tnt_sandbox.yml
```
3. Dump new routes from a live environment locally. We recommend to keep them in a separate file
```
vgs --tenant=tnt_live --environment=live route --dump-all > tnt_live.yml
```
3. Update migrated routes in `tnt_live.yml`, if needed. Typically you may need to make changes to some upstream configurations that you were using when testing.
4. Sync changes back to tnt_live
```
vgs --tenant=tnt_live --environment=live route --sync-all < tnt_live.yml
```

