{"id":21971381,"url":"https://github.com/cockroachdb/cockroach-operator","last_synced_at":"2025-06-17T09:10:38.536Z","repository":{"id":37266821,"uuid":"222960238","full_name":"cockroachdb/cockroach-operator","owner":"cockroachdb","description":"k8s operator for CRDB","archived":false,"fork":false,"pushed_at":"2025-06-10T07:58:49.000Z","size":41966,"stargazers_count":301,"open_issues_count":187,"forks_count":98,"subscribers_count":48,"default_branch":"master","last_synced_at":"2025-06-13T14:02:30.729Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/cockroachdb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2019-11-20T14:48:34.000Z","updated_at":"2025-06-10T07:58:53.000Z","dependencies_parsed_at":"2023-12-12T01:29:12.057Z","dependency_job_id":"5f2b4f46-5ba9-4211-853f-cfc197ab48cb","html_url":"https://github.com/cockroachdb/cockroach-operator","commit_stats":null,"previous_names":["cockroachlabs/crdb-operator"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/cockroachdb/cockroach-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cockroachdb%2Fcockroach-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cockroachdb%2Fcockroach-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cockroachdb%2Fcockroach-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cockroachdb%2Fcockroach-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cockroachdb","download_url":"https://codeload.github.com/cockroachdb/cockroach-operator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cockroachdb%2Fcockroach-operator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260326793,"owners_count":22992388,"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":[],"created_at":"2024-11-29T14:50:21.343Z","updated_at":"2025-06-17T09:10:38.527Z","avatar_url":"https://github.com/cockroachdb.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# CockroachDB Kubernetes Operator\n\nThe CockroachDB Kubernetes Operator deploys CockroachDB on a Kubernetes cluster. You can use the Operator to manage the configuration of a running CockroachDB cluster, including:\n\n- Authenticating certificates\n- Configuring resource requests and limits\n- Scaling the cluster\n- Performing a rolling upgrade\n\n## Build Status\n\nGKE Nightly: [![GKE Nightly](https://teamcity.cockroachdb.com/guestAuth/app/rest/builds/buildType:Cockroach_CockroachOperator_Nightlies_GkeNightly/statusIcon)](https://teamcity.cockroachdb.com/viewType.html?buildTypeId=Cockroach_CockroachOperator_Nightlies_GkeNightly)\n\nOpenShift Nightly: [![OpenShift Nightly](https://teamcity.cockroachdb.com/guestAuth/app/rest/builds/buildType:Cockroach_CockroachOperator_Nightlies_OpenShiftNightly/statusIcon)](https://teamcity.cockroachdb.com/viewType.html?buildTypeId=Cockroach_CockroachOperator_Nightlies_OpenShiftNightly)\n\n## Limitations\n\n- The Operator currently runs on GKE. VMware Tanzu, EKS, and AKS have not been tested.\n- The Operator does not yet support [multiple Kubernetes clusters for multi-region deployments](https://www.cockroachlabs.com/docs/stable/orchestrate-cockroachdb-with-kubernetes-multi-cluster.html#eks).\n- [Migrating from a deployment using the Helm Chart to the Operator](https://github.com/cockroachdb/cockroach-operator/issues/140) has not been defined or tested.\n- The Operator does not yet [automatically create an ingress object](https://github.com/cockroachdb/cockroach-operator/issues/76).\n- The Operator has not been tested with [Istio](https://istio.io/).\n\n## Prerequisites\n\n- Kubernetes 1.18 or higher\n- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)\n- A GKE cluster (`n2-standard-4` is the minimum requirement for testing)\n\n## Install the Operator\n\nApply the custom resource definition (CRD) for the Operator:\n\n```\nkubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/crds.yaml\n```\n\nApply the Operator manifest. By default, the Operator is configured to install in the `cockroach-operator-system`\nnamespace. To use the Operator in a custom namespace, download the [Operator\nmanifest](https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml) and edit all\ninstances of `namespace: cockroach-operator-system` to specify your custom namespace. Then apply this version of the\nmanifest to the cluster with `kubectl apply -f {local-file-path}` instead of using the command below.\n\n```\nkubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml\n```\n\nValidate that the Operator is running:\n\n```\nkubectl get pods\n```\n\n```\nNAME                                  READY   STATUS    RESTARTS   AGE\ncockroach-operator-6f7b86ffc4-9ppkv   1/1     Running   0          54s\n```\n\n## Start CockroachDB\n\nDownload the [`example.yaml`](https://github.com/cockroachdb/cockroach-operator/blob/master/examples/example.yaml) custom resource.\n\n\u003e **Note:** The latest stable CockroachDB release is specified by default in `image.name`.\n\n### Resource requests and limits\n\nBy default, the Operator allocates 2 CPUs and 8Gi memory to CockroachDB in the Kubernetes pods. These resources are appropriate for `n2-standard-4` (GCP) and `m5.xlarge` (AWS) machines.\n\nOn a production deployment, you should modify the `resources.requests` object in the custom resource with values appropriate for your workload. For details, see the [CockroachDB documentation](https://www.cockroachlabs.com/docs/stable/operate-cockroachdb-kubernetes.html#allocate-resources).\n\n### Certificate signing\n\nThe Operator generates and approves 1 root and 1 node certificate for the cluster.\n\n### Apply the custom resource\n\nApply `example.yaml`:\n\n```\nkubectl create -f example.yaml\n```\n\nCheck that the pods were created:\n\n```\nkubectl get pods\n```\n\n```\nNAME                                  READY   STATUS    RESTARTS   AGE\ncockroach-operator-6f7b86ffc4-9t9zb   1/1     Running   0          3m22s\ncockroachdb-0                         1/1     Running   0          2m31s\ncockroachdb-1                         1/1     Running   0          102s\ncockroachdb-2                         1/1     Running   0          46s\n```\n\nEach pod should have `READY` status soon after being created.\n\n## Access the SQL shell\n\nTo use the CockroachDB SQL client, first launch a secure pod running the `cockroach` binary.\n\n```\nkubectl create -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/examples/client-secure-operator.yaml\n```\n\nGet a shell into the client pod:\n\n```\nkubectl exec -it cockroachdb-client-secure -- ./cockroach sql --certs-dir=/cockroach/cockroach-certs --host=cockroachdb-public\n```\n\nIf you want to [access the DB Console](#access-the-db-console), create a SQL user with a password while you're here:\n\n```\nCREATE USER roach WITH PASSWORD 'Q7gc8rEdS';\n```\n\nThen assign `roach` to the `admin` role to enable access to [secure DB Console pages](https://www.cockroachlabs.com/docs/stable/ui-overview.html#db-console-security):\n\n```\nGRANT admin TO roach;\n```\n\n```\n\\q\n```\n\n## Access the DB Console\n\nTo access the cluster's [DB Console](https://www.cockroachlabs.com/docs/stable/ui-overview.html), port-forward from your local machine to the `cockroachdb-public` service:\n\n```\nkubectl port-forward service/cockroachdb-public 8080\n```\n\nAccess the DB Console at `https://localhost:8080`.\n\n### Scale the CockroachDB cluster\n\n\u003e **Note:** Due to a [known issue](https://github.com/cockroachdb/cockroach-operator/issues/542), automatic pruning of PVCs is currently disabled by default. This means that after decommissioning and removing a node, the Operator will not remove the persistent volume that was mounted to its pod. If you plan to eventually scale up the cluster after scaling down, you will need to manually delete any PVCs that were orphaned by node removal before scaling up. For more information, see the [documentation](https://www.cockroachlabs.com/docs/stable/operate-cockroachdb-kubernetes.html#remove-nodes).\n\nTo scale the cluster up and down, modify `nodes` in the custom resource. For details, see the [CockroachDB documentation](https://www.cockroachlabs.com/docs/stable/operate-cockroachdb-kubernetes#scale-the-cluster).\n\nDo **not** scale down to fewer than 3 nodes. This is considered an anti-pattern on CockroachDB and will cause errors.\n\n\u003e **Note:** You must scale by updating the `nodes` value in the Operator configuration. Using `kubectl scale statefulset \u003ccluster-name\u003e --replicas=4` will result in new pods immediately being terminated.\n\n### Upgrade the CockroachDB cluster\n\nPerform a rolling upgrade by changing `image.name` in the custom resource. For details, see the [CockroachDB documentation](https://www.cockroachlabs.com/docs/stable/operate-cockroachdb-kubernetes#upgrade-the-cluster).\n\n## Stop the CockroachDB cluster\n\nDelete the custom resource:\n\n```\nkubectl delete -f example.yaml\n```\n\nRemove the Operator:\n\n```\nkubectl delete -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml\n```\n\n\u003e **Note:** If you want to delete the persistent volumes and free up the storage used by CockroachDB, be sure you have a backup copy of your data. Data **cannot** be recovered once the persistent volumes are deleted. For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/run-application/delete-stateful-set/#persistent-volumes). \n\n# Releases\n\nWe have a few phases to our releases. The first involves creating a new branch, updating the version, and then getting a\nPR merged into master with all of the generated files.\n\nSubsequent steps will need to be carried out in TeamCity and RedHat Connect.\n\n## Creating a new release PR\n\nFrom a clean, up-to-date master (seriously...check), run the following where `\u003cversion\u003e` is the desired new version\n(e.g. `2.2.0`).\n\n```\n$ make release/new VERSION=\u003cversion\u003e\n...\n...\n$ git push origin release-$(cat version.txt)\n```\n\nThis will do the following for you:\n\n- Create a new branch named `release-\u003cversion\u003e`\n- Update version.txt\n- Generate the manifest, bundles, etc.\n- Commit the changes with the message `Bump version to \u003cversion\u003e`.\n- Push to a new branch on origin (that wasn't automated)\n\n## Tag the release\n\nAfter the PR is merged run the following to create the tag (you'll need to be a member of CRL to do this).\n\n    git tag v$(cat version.txt)\n    git push upstream v$(cat version.txt)\n\n## Run Release Automation\n\nFrom here, the rest of the release process is done with TeamCity. A CRL team member will need to perform some manual\nsteps in RedHat Connect as well. Ping one of us in Slack for info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcockroachdb%2Fcockroach-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcockroachdb%2Fcockroach-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcockroachdb%2Fcockroach-operator/lists"}