{"id":23577538,"url":"https://github.com/couchbaselabs/couch-formation-core","last_synced_at":"2025-07-01T12:04:12.734Z","repository":{"id":216685380,"uuid":"741977791","full_name":"couchbaselabs/couch-formation-core","owner":"couchbaselabs","description":"Couchbase deploy automation for AWS, GCP, Azure, Capella, and Docker ","archived":false,"fork":false,"pushed_at":"2024-12-05T17:05:49.000Z","size":1290,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-05T23:15:02.244Z","etag":null,"topics":["automation","capella","cloud","couchbase","couchbase-sync-gateway","devops"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbaselabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-11T14:04:38.000Z","updated_at":"2024-12-05T17:05:53.000Z","dependencies_parsed_at":"2024-01-12T01:30:03.724Z","dependency_job_id":"52f0fdef-ce45-481f-8974-ae57df5b9c60","html_url":"https://github.com/couchbaselabs/couch-formation-core","commit_stats":{"total_commits":152,"total_committers":1,"mean_commits":152.0,"dds":0.0,"last_synced_commit":"91b74e88eeffcd2d06fc6a4359765a869e10f7d8"},"previous_names":["couchbaselabs/couch-formation-core"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/couchbaselabs/couch-formation-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fcouch-formation-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fcouch-formation-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fcouch-formation-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fcouch-formation-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbaselabs","download_url":"https://codeload.github.com/couchbaselabs/couch-formation-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbaselabs%2Fcouch-formation-core/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260079509,"owners_count":22955708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","capella","cloud","couchbase","couchbase-sync-gateway","devops"],"created_at":"2024-12-26T22:29:29.959Z","updated_at":"2025-07-01T12:04:12.698Z","avatar_url":"https://github.com/couchbaselabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](doc/couch-formation-1.png)\n# Couch Formation 4.0.2\nToolset for running and managing Couchbase assets in the cloud.\n\n## Disclaimer\n\n\u003e 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````\npip install --user couchformation\n````\n````\nexport PATH=$(python -m site --user-base)/bin:$PATH\n````\n### Install (virtual environment method):\n#### Linux\nCreate virtual environment:\n````\npython -m venv couchformation\n````\nActivate virtual environment:\n````\n. couchformation/bin/activate\n````\nInstall Couch Formation into the virtual environment:\n````\npip install couchformation\n````\n#### Activate Windows virtual environment using cmd\n````\ncouchformation\\Scripts\\activate.bat\n````\n#### Active Windows virtual environment using PowerShell\n````\ncouchformation\\Scripts\\Activate.ps1\n````\n### Install directly from GitHub repo:\n````\npip 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## Providing tags in AWS\n```\ncloudmgr create --build cbs --cloud aws --project test-db --name testdb --region us-east-1 --auth_mode sso --ssh_key /Users/jdoe/.ssh/jdoe-default-key-pair.pem --os_id ubuntu --os_version 22.04 --machine_type 8x32 --quantity 3 --tags user:john.doe@example.com\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 --profile pytest --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 --profile pytest --quantity 2 --machine_type 4x8 --type mobile --connect test-cluster\n```\n\n## Columnar example\n```\ncloudmgr create --build columnar --cloud capella --project test-project --name test-cluster --profile pytest --provider aws --region us-east-1 --machine_type 4x32 --quantity 1\n```\n\n## Capella automatic peering\nUse the `--peer_project` argument to provide a project for peering:\n```\ncloudmgr create --build capella --cloud capella --project test-capella --name testdb --profile test --provider aws --region us-east-1 --cidr 10.12.4.0/23 --machine_type 8x32 --quantity 3 --peer_project test-node\n```\n\nDeploy the peer project (if not already deployed):\n```\ncloudmgr deploy --project test-node\n```\nThen deploy the Capella project:\n```\ncloudmgr deploy --project test-capella\n```\nNOTE: Automatic peering is only supported with AWS and GCP.\n\n## Additional commands\n### Destroy a project:\n```\ncloudmgr destroy --project dev01\n```\n\n### List node details (including IP addresses and generated passwords):\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### List all projects and services:\n```\ncloudmgr list\n```\n\n### Display detailed information about configured services in a project:\n```\ncloudmgr show --project dev01\n```\n\n### Recall the CLI commands that were used to add services to a project (you can use this to copy and paste to create a new project):\n```\ncloudmgr cli --project dev01\n```\n\n### Change the values for parameters in a previously created service:\n```\ncloudmgr update --project dev01 --name node --machine_type 8x32\n```\n\n### Change the values for parameters for a service node group:\n```\ncloudmgr update --project dev01 --name testdb --group 2 --machine_type 4x16\n```\n\n### Remove a service from a project:\n```\ncloudmgr remove --project dev01 --name testdb\n```\n\n### Remove an entire project:\n```\ncloudmgr clean --project dev01\n```\n\n### Create a SSH key to use with Couch Formation:\n```\ncloudmgr ssh create\n```\n\n### Set configuration parameters (see table below for all supported parameters):\n```\ncloudmgr config set ssh.key /Users/jdoe/.ssh/jdoe-default-key-pair.pem\n```\n\n### Get help on supported parameters:\n```\ncloudmgr help --cloud aws\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 application-default login``` 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\nThe automation for Capella uses the v4 public API. To use the automation, set the `capella.token` and `capella.user` configuration parameters.\n```\ncloudmgr config set capella.token dGhpcyBpcyBhIHNhbXBsZSBzdHJpbmcgZm9yIFJFQURNRS5tZC4uCg==\ncloudmgr config set capella.user john.doe@example.com\n```\nBy default, the Couch Formation project is used as the Capella project. To use a different Capella project, set the `capella.project` parameter.\n```\ncloudmgr config set capella.project my-project\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## Configuration Parameters\n| Parameter       | Description                      |\n|-----------------|----------------------------------|\n| aws.tags        | Default tags for AWS deployments |\n| capella.token   | Capella API token                |\n| capella.user    | Capella user email address       |\n| capella.user.id | Capella user ID                  |\n| capella.project | Capella project                  |\n| ssh.key         | Default SSH key                  |\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| cbscert    | Couchbase Server with cert auth |\n| cbsc       | Couchbase Community Edition     |\n| sgw        | Sync Gateway                    |\n| capella    | Capella Database                |\n| columnar   | Capella Columnar                |\n| generic    | Base configured node from image |\n| database   | Generic database node           |\n| windev     | Windows development host        |\n\n## Troubleshooting\nLog files are written to ```.config/couch-formation/log```.\n\u003cbr\u003e\u003cbr\u003e\nTo create a support bundle with diagnostic information, use the ```dump``` command.\n```\ncloudmgr dump\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbaselabs%2Fcouch-formation-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbaselabs%2Fcouch-formation-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbaselabs%2Fcouch-formation-core/lists"}