# Couch Formation 4.0.0a30
Toolset for running and managing Couchbase assets in the cloud.
## Disclaimer
> This package is **NOT SUPPORTED BY COUCHBASE**. The toolset is under active development, therefore features and functionality can change.
## Prerequisites
- Python 3.8+
- Cloud CLI/SDKs
- [AWS CLI](https://aws.amazon.com/cli/)
- [Google Cloud CLI](https://cloud.google.com/sdk/docs/quickstart)
- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
- Homebrew (for macOS)
## Quick Start
### Install (pip user local method):
````
pip3 install --user couchformation
````
````
export PATH=$(python3 -m site --user-base)/bin:$PATH
````
### Install (virtual environment method):
````
python3 -m venv couchformation
````
````
cd couchformation
````
````
. bin/activate
````
````
pip3 install couchformation
````
### Install directly from GitHub repo:
````
pip3 install --user git+https://github.com/couchbaselabs/couch-formation-core
````
## Basic example
### Configure and deploy a Couchbase Server cluster:
````
cloudmgr create --build cbs --cloud gcp --project test-gcp --name test-cluster --region us-central1 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16
````
### Deploy the project:
````
cloudmgr deploy --project test-gcp
````
## MDS example
### Create the initial service group:
```
cloudmgr create --build cbs --cloud aws --project dev01 --name testdb01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
### Add a second service group:
```
cloudmgr add --build cbs --cloud aws --project dev01 --name testdb01 --region us-east-2 --quantity 2 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32 --services analytics
```
## Multiservice project example
Configure a 3 node Couchbase Server cluster in US Ease, another 3 node Couchbase Server cluster in US West, plus a Linux generic node and a Windows generic node to run an application.
```
cloudmgr create --build cbs --cloud aws --project dev01 --name source01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
```
cloudmgr create --build cbs --cloud aws --project dev01 --name target01 --region us-west-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
```
cloudmgr create --build generic --cloud aws --project dev01 --name app01 --region us-east-2 --quantity 1 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
```
cloudmgr create --build generic --cloud aws --project dev01 --name app02 --region us-east-2 --quantity 1 --os_id windows --os_version 2022 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
## Custom services example
```
cloudmgr create --build cbs --cloud aws --project eventing --name eventing01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32 --services data,index,query,eventing
```
## Sync Gateway example
### Create the Couchbase Server cluster:
```
cloudmgr create --build cbs --cloud aws --project sgw-dev01 --name devdb01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16
```
### Create a Sync Gateway and connect to the cluster:
```
cloudmgr create --build sgw --cloud aws --project sgw-dev01 --name gateway --region us-east-2 --quantity 1 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16 --connect devdb01
```
## Capella example
For Capella the Couch Formation project aligns with the Capella project.
```
cloudmgr create --build capella --cloud capella --project test-project --name test-cluster --region us-east-2 --quantity 3 --provider aws --machine_type 4x16
```
Optionally create an app service (Sync Gateway in Capella) and attach it to a Capella database.
```
cloudmgr create --build capella --cloud capella --project test-project --name test-app-svc --quantity 2 --machine_type 4x8 --type mobile --connect test-cluster
```
## Additional CLI examples
### Destroy a project:
```
cloudmgr destroy --project dev01
```
### List node IP addresses:
```
cloudmgr list --project dev01
```
### Operate on only one service in a project:
```
cloudmgr deploy --project dev01 --name source01
```
## AWS SSO Support
### Setup AWS CLI SSO:
```
aws configure sso
```
### SSO Integration:
Use the auth_mode option to enable SSO integration. Couch Formation will open a browser for you to complete the SSO process, or you will have to paste the link provided into a browser to continue.
```
cloudmgr create --build cbs --cloud aws --project dev01 --name testdb01 --auth_mode sso --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32
```
## AWS Default Authentication
Configure the AWS CLI via an appropriate method based on your IAM settings. For example use ```aws configure``` to configure long term credentials, or manually set the access parameters in ```.aws/credentials``` or with environment variables. Couch Formation accepts an optional ```--profile``` service configuration parameter to use a specific auth profile. Check [here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new) for more information.
## GCP Default Authentication
For Google Cloud use ```gcloud auth``` to configure CLI access. Check [here](https://cloud.google.com/sdk/gcloud/reference/auth) for more information.
## Azure Default Authentication
For Azure use ```az login``` to configure CLI access. Check [here](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli-interactively) for more information.
## Capella Support
### Credentials Directory
The automation for Capella uses the v4 public API. To use the automation, create an API key in the Capella UI and save it to a file named ```default-api-key-token.txt``` in a directory named ```.capella``` in your home directory.
```
.capella
├── credentials
├── default-api-key-token.txt
├── project-api-key-token.txt
└── test-api-key-token.txt
```
Credentials file format:
```
[default]
api_host = cloudapi.cloud.couchbase.com
token_file = default-api-key-token.txt
account_email = john.doe@example.com
[project]
token_file = project-api-key-token.txt
```
## Windows
Download and install a 64-bit version of Python 3.8+ from [here](https://www.python.org/downloads/windows/). Use the ```Run as Administrator``` option to start PowerShell and then install Couch Formation with ```pip```. Once the installation is complete, it will be available for all users (launch a PowerShell window as your login user to use Couch Formation). You should install the ```wheel``` pacakge before you install Couch Formation.
```
pip3 install wheel
```
```
pip3 install couchformation
```
## Operating System Information
| ID | Operating System | Versions | AWS User | GCP User | Azure User |
|---------------|--------------------------|--------------|---------------|-----------|------------|
| amzn | Amazon Linux | 2, 2023 | ec2-user | N/A | N/A |
| rhel | Red Hat Enterprise Linux | 8, 9 | ec2-user | admin | rhel |
| centos | CentOS | 8 | centos | centos | centos |
| ol | Oracle Linux | 8, 9 | ec2-user | N/A | N/A |
| rocky | Rocky Linux | 8, 9 | rocky | rocky | N/A |
| fedora | Fedora | 34 | core | fedora | N/A |
| sles | SUSE Linux | 12, 15 | ec2-user | admin | sles |
| opensuse-leap | openSUSE | 15 | ec2-user | admin | sles |
| ubuntu | Ubuntu Linux | 20.04, 22.04 | ubuntu | ubuntu | ubuntu |
| debian | Debian Linux | 10, 11 | admin | admin | debian |
| windows | Windows Server | 2019, 2022 | Administrator | adminuser | adminuser |
| macos | macOS | 13, 14 | ec2-user | N/A | N/A |
## Build Types
| Build Type | Description |
|------------|---------------------------------|
| cbs | Couchbase Server |
| sgw | Sync Gateway |
| capella | Capella Database |
| generic | Base configured node from image |
## Troubleshooting
Log files are written to ```.config/couch-formation/log```.
Raw data
{
"_id": null,
"home_page": "https://github.com/mminichino/couch-formation-core",
"name": "couchformation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "couchbase, devops, automation",
"author": "Michael Minichino",
"author_email": "info@unix.us.com",
"download_url": "https://files.pythonhosted.org/packages/83/ef/205868d44c31a16a86d7bdda250d2bebab70bc8c242f9d5ac297f37f5fd8/couchformation-4.0.0a30.tar.gz",
"platform": null,
"description": "\n# Couch Formation 4.0.0a30\nToolset for running and managing Couchbase assets in the cloud.\n\n## Disclaimer\n\n> This package is **NOT SUPPORTED BY COUCHBASE**. The toolset is under active development, therefore features and functionality can change.\n\n## Prerequisites\n- Python 3.8+\n- Cloud CLI/SDKs\n - [AWS CLI](https://aws.amazon.com/cli/)\n - [Google Cloud CLI](https://cloud.google.com/sdk/docs/quickstart)\n - [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)\n- Homebrew (for macOS)\n\n## Quick Start\n### Install (pip user local method):\n````\npip3 install --user couchformation\n````\n````\nexport PATH=$(python3 -m site --user-base)/bin:$PATH\n````\n### Install (virtual environment method):\n````\npython3 -m venv couchformation\n````\n````\ncd couchformation\n````\n````\n. bin/activate\n````\n````\npip3 install couchformation\n````\n### Install directly from GitHub repo:\n````\npip3 install --user git+https://github.com/couchbaselabs/couch-formation-core\n````\n\n## Basic example\n### Configure and deploy a Couchbase Server cluster:\n````\ncloudmgr create --build cbs --cloud gcp --project test-gcp --name test-cluster --region us-central1 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16\n````\n### Deploy the project:\n````\ncloudmgr deploy --project test-gcp\n````\n\n## MDS example\n### Create the initial service group:\n```\ncloudmgr create --build cbs --cloud aws --project dev01 --name testdb01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n### Add a second service group:\n```\ncloudmgr add --build cbs --cloud aws --project dev01 --name testdb01 --region us-east-2 --quantity 2 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32 --services analytics\n```\n\n## Multiservice project example\nConfigure a 3 node Couchbase Server cluster in US Ease, another 3 node Couchbase Server cluster in US West, plus a Linux generic node and a Windows generic node to run an application.\n```\ncloudmgr create --build cbs --cloud aws --project dev01 --name source01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n```\ncloudmgr create --build cbs --cloud aws --project dev01 --name target01 --region us-west-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n```\ncloudmgr create --build generic --cloud aws --project dev01 --name app01 --region us-east-2 --quantity 1 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n```\ncloudmgr create --build generic --cloud aws --project dev01 --name app02 --region us-east-2 --quantity 1 --os_id windows --os_version 2022 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n\n## Custom services example\n```\ncloudmgr create --build cbs --cloud aws --project eventing --name eventing01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32 --services data,index,query,eventing\n```\n\n## Sync Gateway example\n### Create the Couchbase Server cluster:\n```\ncloudmgr create --build cbs --cloud aws --project sgw-dev01 --name devdb01 --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16\n```\n### Create a Sync Gateway and connect to the cluster:\n```\ncloudmgr create --build sgw --cloud aws --project sgw-dev01 --name gateway --region us-east-2 --quantity 1 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 4x16 --connect devdb01\n```\n\n## Capella example\nFor Capella the Couch Formation project aligns with the Capella project.\n```\ncloudmgr create --build capella --cloud capella --project test-project --name test-cluster --region us-east-2 --quantity 3 --provider aws --machine_type 4x16\n```\nOptionally create an app service (Sync Gateway in Capella) and attach it to a Capella database.\n```\ncloudmgr create --build capella --cloud capella --project test-project --name test-app-svc --quantity 2 --machine_type 4x8 --type mobile --connect test-cluster\n```\n\n## Additional CLI examples\n### Destroy a project:\n```\ncloudmgr destroy --project dev01\n```\n\n### List node IP addresses:\n```\ncloudmgr list --project dev01\n```\n\n### Operate on only one service in a project:\n```\ncloudmgr deploy --project dev01 --name source01\n```\n\n## AWS SSO Support\n### Setup AWS CLI SSO:\n```\naws configure sso\n```\n### SSO Integration:\nUse the auth_mode option to enable SSO integration. Couch Formation will open a browser for you to complete the SSO process, or you will have to paste the link provided into a browser to continue.\n```\ncloudmgr create --build cbs --cloud aws --project dev01 --name testdb01 --auth_mode sso --region us-east-2 --quantity 3 --os_id ubuntu --os_version 22.04 --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --machine_type 8x32\n```\n\n## AWS Default Authentication\nConfigure the AWS CLI via an appropriate method based on your IAM settings. For example use ```aws configure``` to configure long term credentials, or manually set the access parameters in ```.aws/credentials``` or with environment variables. Couch Formation accepts an optional ```--profile``` service configuration parameter to use a specific auth profile. Check [here](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new) for more information.\n\n## GCP Default Authentication\nFor Google Cloud use ```gcloud auth``` to configure CLI access. Check [here](https://cloud.google.com/sdk/gcloud/reference/auth) for more information.\n\n## Azure Default Authentication\nFor Azure use ```az login``` to configure CLI access. Check [here](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli-interactively) for more information.\n\n## Capella Support\n### Credentials Directory\nThe automation for Capella uses the v4 public API. To use the automation, create an API key in the Capella UI and save it to a file named ```default-api-key-token.txt``` in a directory named ```.capella``` in your home directory.\n```\n.capella\n\u251c\u2500\u2500 credentials\n\u251c\u2500\u2500 default-api-key-token.txt\n\u251c\u2500\u2500 project-api-key-token.txt\n\u2514\u2500\u2500 test-api-key-token.txt\n```\nCredentials file format:\n```\n[default]\napi_host = cloudapi.cloud.couchbase.com\ntoken_file = default-api-key-token.txt\naccount_email = john.doe@example.com\n\n[project]\ntoken_file = project-api-key-token.txt\n```\n## Windows\nDownload and install a 64-bit version of Python 3.8+ from [here](https://www.python.org/downloads/windows/). Use the ```Run as Administrator``` option to start PowerShell and then install Couch Formation with ```pip```. Once the installation is complete, it will be available for all users (launch a PowerShell window as your login user to use Couch Formation). You should install the ```wheel``` pacakge before you install Couch Formation.\n```\npip3 install wheel\n```\n```\npip3 install couchformation\n```\n## Operating System Information\n\n| ID | Operating System | Versions | AWS User | GCP User | Azure User |\n|---------------|--------------------------|--------------|---------------|-----------|------------|\n| amzn | Amazon Linux | 2, 2023 | ec2-user | N/A | N/A |\n| rhel | Red Hat Enterprise Linux | 8, 9 | ec2-user | admin | rhel |\n| centos | CentOS | 8 | centos | centos | centos |\n| ol | Oracle Linux | 8, 9 | ec2-user | N/A | N/A |\n| rocky | Rocky Linux | 8, 9 | rocky | rocky | N/A |\n| fedora | Fedora | 34 | core | fedora | N/A |\n| sles | SUSE Linux | 12, 15 | ec2-user | admin | sles |\n| opensuse-leap | openSUSE | 15 | ec2-user | admin | sles |\n| ubuntu | Ubuntu Linux | 20.04, 22.04 | ubuntu | ubuntu | ubuntu |\n| debian | Debian Linux | 10, 11 | admin | admin | debian |\n| windows | Windows Server | 2019, 2022 | Administrator | adminuser | adminuser |\n| macos | macOS | 13, 14 | ec2-user | N/A | N/A |\n\n## Build Types\n\n| Build Type | Description |\n|------------|---------------------------------|\n| cbs | Couchbase Server |\n| sgw | Sync Gateway |\n| capella | Capella Database |\n| generic | Base configured node from image |\n\n## Troubleshooting\nLog files are written to ```.config/couch-formation/log```.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Couchbase Cloud Automation",
"version": "4.0.0a30",
"project_urls": {
"Homepage": "https://github.com/mminichino/couch-formation-core"
},
"split_keywords": [
"couchbase",
" devops",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "83ef205868d44c31a16a86d7bdda250d2bebab70bc8c242f9d5ac297f37f5fd8",
"md5": "f8a5599d92df88ee08729e66d77a0a06",
"sha256": "ae3e969ae4be03536502f677467f84a20f739438a60ebebda743009edecd7743"
},
"downloads": -1,
"filename": "couchformation-4.0.0a30.tar.gz",
"has_sig": false,
"md5_digest": "f8a5599d92df88ee08729e66d77a0a06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 204591,
"upload_time": "2024-04-08T03:58:21",
"upload_time_iso_8601": "2024-04-08T03:58:21.875404Z",
"url": "https://files.pythonhosted.org/packages/83/ef/205868d44c31a16a86d7bdda250d2bebab70bc8c242f9d5ac297f37f5fd8/couchformation-4.0.0a30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 03:58:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mminichino",
"github_project": "couch-formation-core",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "couchformation"
}
JSON
