Skip to content

Commit

Permalink
Merge pull request #2404 from EnterpriseDB/release/2022-03-03
Browse files Browse the repository at this point in the history 
Release: 2022-03-03
  • Loading branch information
@drothery-edb
drothery-edb authored Mar 3, 2022
2 parents 9578d6e + 3d9d753 commit 6690dc4
Show file tree
Hide file tree
Showing 6 changed files with 284 additions and 66 deletions.
121 changes: 73 additions & 48 deletions product_docs/docs/biganimal/release/reference/cli.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The CLI is available for Linux, MacOS, and Windows operating systems.
curl -LO "https://cli.biganimal.com/download/$(uname -s)/$(uname -m)/latest/biganimal"
```

- For all operating systems, download the executable binary [here](https://cli.biganimal.com/).
- For all operating systems, download the executable binary [here](https://cli.biganimal.com/). After downloading, move the binary executable under a directory on your executable search path.

### (Optional) Validate the download

Expand All @@ -36,11 +36,9 @@ The CLI is available for Linux, MacOS, and Windows operating systems.
1. Download the SHA256 checksum code for MacOS distribution from the [BigAnimal CLI](https://cli.biganimal.com) page and store it as a local file such as `biganimal_darwin_amd64.sha256`. Alternatively, click on the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
2. From MacOS terminal, validate the binary executable file against the checksum file:
```
echo "$(<biganimal_darwin_amd64.sha256) biganimal" | shasum -c
echo "$(<biganimal_darwin_amd64.sha256) biganimal" | shasum -a256 -c
```
## Command reference

Use the `-h` or `--help` flags for more information on the CLI commands. You can use the flag on the `biganimal` command to get a listing of all the available commands (`biganimal -h`) or on a subcommand to get information on that particular command (for example, `biganimal create-cluster -h`).

## Authenticate as a valid user

Expand All @@ -57,57 +55,58 @@ press [Enter] to continue in the web browser...
Credential "ba-user1" created!
```

You can create multiple credentials for different BigAnimal accounts and then set one as context of your current management session. Use `show-credentials` to list all available credentials and use `set-context-credential` to set a default credential for the current context. For example:
You can create multiple credentials for different BigAnimal accounts and then set one as context of your current management session. Use `show-credentials` to list all available credentials and use `config set context_credential` to set a default credential for the current context. For example:

```
$ biganimal show-credentials
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Credentials ┃
┃ Credentials ┃
┣━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┫
┃ Name ┃ Address ┃ Port ┃ TokenType ┃ AccessToken ┃ RefreshToken ┃ IdToken ┃
┣━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━╋━━━━━━━━━━━━┫
┃ ba-user1 ┃ portal.biganimal.com ┃ 443 ┃ Bearer ┃ ********** ┃ ********** ┃ ********** ┃
┃ ba-user2 ┃ portal.biganimal.com ┃ 443 ┃ Bearer ┃ ********** ┃ ********** ┃ ********** ┃
┗━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━┻━━━━━━━━━━━━┛
$ biganimal set-context-credentials ba-user1
$ biganimal config set context_credential ba-user1
The credential ba-user1 has been set up
```

## Configuring

The initial running of the CLI creates a hidden configuration folder in your user root directory. For example, for Linux it’s `${HOME}/.edb-cli`. The CLI persists the configuration file in this directory as well as the credentials.

Don’t edit files in this directory directly. Instead, use the following commands to query and update the configuration.

### Confirmation commands
Don’t edit files in this directory directly. Instead, use the `config` subcommand to list and update the configuration settings of the CLI. Use the following command to get detailed usage and available configurations inforamtion:
```shell
$ biganimal config
```

| Command | Description |
| ----------------- | ---------------------------------------------------------------- |
| `get-confirm` | Get the current value for the confirmation mode |
| `enable-confirm` | Enable confirmation when creating/deleting/updating resources |
| `disable-confirm` | Disable confirmation before creating/deleting/updating resources |
### Available configuration settings

### Prompt mode commands
| Setting | Description |
| -------------------- | ---------------------------------------------------------------- |
| `context_credential` | The default credential used in the following commands. |
| `output_mode` | The command line output format: table, json, xml, or yaml. |
| `confirm_mode` | If enabled, create/update/delete commands require user confirmation. |
| `interactive_mode` | If enabled, CLI prompts for missing flags and available options. See [Interactive mode](#interactive-mode) for more information.|
| `check_update_mode` | If enabled, CLI detects new updates automatically and prompts for download. |

| Command | Description |
| ---------------- | ------------------------------------------------- |
| `get-prompt` | Get the current value for the prompt mode |
| `enable-prompt` | Enable prompting for missing required parameters |
| `disable-prompt` | Disable prompting for missing required parameters |

### Output format commands
## Usability features

| Command | Description |
| ------------ | --------------------------------------------------------------- |
| `get-output` | Get the current output mode |
| `set-output` | Set the output mode, valid modes are [ json, yaml, xml, table ] |
### Online command reference and help
Use the `-h` or `--help` flags for more information on the CLI commands. You can use these flags on the `biganimal` command to get a listing of all the available subcommands (`biganimal -h`) or on a subcommand to get information on that particular command (for example, `biganimal create-cluster -h`).

### Auto completion
You can enable command line auto completion for bash, fish, powershell, and zsh. To set up auto completion:

### Auto Completion
```shell
$ biganimal completion
```

The CLI supports command line auto completion for bash, fish, powershell, and zsh. The following command describes how to set auto completion up in bash:
### Interactive mode
In interactive mode, the CLI prompts you for any missing mandatory flags and lists any available options for your current context. To enable interactive mode:

```shell
$ ba completion bash --help
$ biganimal config set interactive_mode on
```

## Sample use cases
Expand All @@ -117,18 +116,19 @@ $ ba completion bash --help
The default mode for the `create-cluster` command is an interactive mode that guides you through the required cluster configuration by providing you with the valid values.

!!!Tip
You can turn off prompting by first using the `biganimal disable-prompt` command. With prompting disabled, if there are any missing required flags, the CLI exits.
You can turn off prompting using the `biganimal config set interactive_mode off` command. With prompting disabled, if there are any missing required flags, the CLI exits with an error.
!!!

```shell
$ biganimal create-cluster
Cluster Name: my-biganimal-cluster
Password: ************
Postgresql Type: EDB Postgres Advanced Server
Postgresql Type: EnterpriseDB PostgreSQL Advanced Server (EPAS)
Postgresql Version: 14
Specify database configuration, for example "application_name=sample_app&array_nulls=true". Leave empty for default configuration:
Provider: Azure
Region: (US) East US
Instance Type: E2s v3(2vCPU, 16GB RAM)
Instance Type: F2s v2(2vCPU, 4GB RAM)
Volume Type: Azure Premium Storage
Use the arrow keys to navigate: ↓ ↑
Volume Properties?
Expand All @@ -146,9 +146,6 @@ Volume Properties?
P60 (8 Ti, 16,000 Provisioned IOPS, 500 Provisioned MB/s)
P70 (16 Ti, 18,000 Provisioned IOPS, 750 Provisioned MB/s)
P80 (32 Ti, 20,000 Provisioned IOPS, 900 Provisioned MB/s)



```

You are prompted to confirm you want to create the cluster. After the cluster creation process is completed, it generates a cluster ID.
Expand All @@ -158,15 +155,21 @@ $ biganimal create-cluster
........
Are you sure you want to Create Cluster ? [y|n]: y
Create Cluster operation is started
Cluster ID is "p-c5rrnksgkgomjq0139s0"
To check current state, run: biganimal status-cluster --id p-c5rrnksgkgomjq0139s0
Cluster ID is "p-gxhkfww1fe"
To check current state, run: biganimal show-clusters --id p-gxhkfww1fe
```

Check your cluster was created successfully using the `show-cluster-status` command:
Check your cluster was created successfully using the `show-clusters` command shown in the return message:

```
$ biganimal show-cluster-status --id p-c5rrnksgkgomjq0139s0
Cluster "my-biganimal-cluster" status is "Cluster in healthy state"
$ biganimal show-clusters --id p-gxhkfww1fe (main|✚118)
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Clusters │
├──────────────┬──────────────────────┬────────────────────┬──────────┬──────────────┬──────────────┬──────────────────────────────┬─────────┤
│ ID │ Name │ Status │ Provider │ Region │ Instance Type │ Postgres Type │ Version │
├──────────────┼──────────────────────┼────────────────────┼──────────┼──────────────┼───────────────┼──────────────────────────────┼─────────┤
│ p-gxhkfww1fe │ my-biganimal-cluster │ Setting up primary │ Azure │ (US) East US │ F2s v2 │ EDB Postgres Advanced Server │ 14 │
└──────────────┴─────────────────────┴────────────────────┴──────────┴──────────────┴───────────────┴──────────────────────────────┴─────────┘
```

### Create a cluster using a configuration file
Expand All @@ -181,14 +184,16 @@ Here is a sample configuration file in YAML format:
clusterName: biganimal_cluster # <string: cluster name>
password: ************ # <string: cluster password (must be at least 12 characters)>
postgresType: epas # <string: postgresType id>
postgresVersion: "14" # <string: postgres version>
postgresVersion: "13" # <string: postgres version>
provider: azure # <string: cloud provider id>
region: francecentral # <string: provider region id>
instanceType: azure:Standard_E2s_v3 # <string: instance type id>
volumeProperties: P1 # <string: volume properties id>
volumeType: azurepremiumstorage # <string: volume type id>
networking: public # <string: input "private" or "public" network>
highAvailability: true # <bool: turn on high-availability>
allowIpRangeMap: [[192.168.1.1/16, Sample Description]] # <list: IP Range to allow network traffic to your cluster from the public Internet>
pgConfigMap: [["application_name","test_app"],["array_nulls","true"]] # <list: Postgres Configuration to set specific database properties>
---
```

Expand All @@ -207,12 +212,12 @@ You can turn off the confirmation step with the `biganimal disable-confirm` comm
To use your BigAnimal cluster, you first need to get your cluster's connection information. To get your cluster's connection information, use the `show-cluster-connection` command:

```
$ biganimal show-cluster-connection --name my-biganimal-cluster --provider azure --region eastus
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Connection String ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ postgres://edb_admin@p-c5vtkei9slcqhepufrd0.brcxzr08qr7rbei1.biganimal.com:5432/edb_admin?sslmode=require ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
$ biganimal show-cluster-connection --name my-biganimal-cluster --provider azure --region eastus (main|✚118)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Connection String ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ postgres://edb_admin@p-gxhkfww1fe.30glixgayvwhtmn3.biganimal.io:5432/edb_admin?sslmode=require ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

!!!tip
Expand Down Expand Up @@ -246,6 +251,26 @@ $ biganimal show-clusters --name my-biganimal-cluster --provider azure --region
"zoneRedundantHa": true,
```

### Update the Postgres configuration of a cluster

To update the Postgres configuration of a BigAnimal cluster directly from the CLI:

```
biganimal update-cluster --id p-gxhkfww1fe --pg-config "application_name=ba_test_app,array_nulls=false"
Update Cluster operation is started
Cluster ID is "p-gxhkfww1fe"
```
To specify multiple configurations, you can use multiple `--pg-config` flags or include multiple configuration settings as a key-value array string separated by commas in one `--pg-config` flag. If a Postgres setting contains a comma, you need to specify it with a separate `--pg-config` flag.

### Restore a cluster
Biganimal continuously backs up your PostgrSQL clusters. Using CLI you can restore a cluster from its backup to any point in time as long as the backups are retained in the backup storage. The restored cluster can be a in another region and with different configurations, you can specify new configurations in restore command. For example:

```
biganimal restore-cluster --name "my-biganimal-cluster" --provider "azure" --region "eastus" --password "mypassword@123" --new-name "my-biganimal-cluster-restored" --new-region="eastus2" --instance-type azure:Standard_E2s_v3 --volume-type azurepremiumstorage --volume-property P1 --networking public --cidr-blocks="10.0.0.1/16=app traffic" --high-availability=true --restore-point 2022-01-26T15:04:05+0800
```

To restore a deleted cluster, use `--from-deleted` flag in the command.

### Delete a cluster

To delete a cluster you no longer need, use the `delete-cluster` command. For example:
Expand Down
Loading

0 comments on commit 6690dc4

Please sign in to comment.