Git Product home page Git Product logo

do-operator's Introduction

do-operator: The Kubernetes Operator for DigitalOcean

do-operator is a Kubernetes operator for managing and consuming DigitalOcean resources from a Kubernetes cluster.

Currently it supports DigitalOcean Managed Databases.

Status

This project is in BETA.

  • This operator should not be depended upon for production use at this time.
  • The CRDs in this project are currently v1alpha1 and may change in the future.
  • DigitalOcean supports this project on a best-effort basis via GitHub issues.

Quick Start

To install the operator on a Kubernetes cluster, you can follow these steps:

  1. Install cert-manager (if not already installed):
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.1/cert-manager.yaml
  1. Generate a DigitalOcean API token and base64 encode it.
  2. Edit the manifest for the most recent version in the releases/ directory. Find the do-operator-do-api-token Secret and replace the access-token value with your base64-encoded token:
apiVersion: v1
data:
  access-token: <your base64-encoded token goes here>
kind: Secret
metadata:
  name: do-operator-do-api-token
  namespace: do-operator-system
type: Opaque
  1. Deploy the manifest:
kubectl apply -f releases/do-operator-<version>.yaml

Usage

See the full documentation in the docs directory.

Development

The do-operator is built using kubebuilder. The Kubebuilder Book is a useful reference for understanding how the pieces fit together.

To test your changes you will need a Kubernetes cluster to run against. We suggest using DigitalOcean Kubernetes, but you may use KIND or any other cluster for testing. The following will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).

Note that you will be billed for any DigitalOcean resources you create via the operator while testing. Make sure you are aware of DigitalOcean's pricing and clean up resources when you're finished testing.

Building and Installing

  1. Install the Custom Resource Definitions:
make install

Note M1 Macbook users: this project is made with Kubebuilder which uses Kustomize v3.8.7 which doesn't have an ARM release and so you need to manually install kustomize for this step to succeed

  1. Build and push your image to the location specified by IMG (in the Makefile):
make docker-build docker-push IMG=<some-registry>/do-operator:tag
  1. Deploy cert-manager, which is necessary to manage certificates for the webhooks.

  2. Generate a DigitalOcean API token to use for testing.

  3. Create a local environment file containing your API token. Note that this file is in the .gitignore so it will remain local to your machine:

cat <<EOF > config/manager/do-api-token.env
access-token=<your api token here>
EOF

The contents of this file will be used to create a secret in the cluster, which is used by the operator deployment to manage resources in your DigitalOcean account.

  1. Deploy the controller to the cluster with the image specified by IMG:
make deploy IMG=<some-registry>/do-operator:tag

Undeploying the Controller

To undeploy the controller from the cluster:

make undeploy

Uninstalling the CRDs

To delete the CRDs from the cluster:

make uninstall

Manually Installing Kustomize (M1 Mac users)

  1. Clone the Kustomize project
  2. Go to the v3.5.7 branch: git checkout kustomize/v3.8.7
  3. Go into the kustomize folder (so from the project root it would be kustomize/kustomize/)
  4. go build .
  5. Now move the generated kustomize binary into the bin directory in this project (create it if it doesn't exist mkdir bin): mv kustomize <project path>/bin/kustomize

Update Go and dependencies

  1. Update Go version in
    1. go.mod
    2. .github/workflows/release.yml
    3. .github/workflows/test.yml
    4. Dockerfile
  2. Update Go dependencies
    go get -u ./...
    go mod tidy
    go mod vendor
  3. Run make test
  4. Create and merge PR

Release

  1. Create release manifest files by running IMG_TAG=vX.Y.Z make release-manifests
  2. Create and merge PR
  3. Trigger the release GitHub action workflow
    • Draft a new release here for the new version
    • Creating a new release will trigger the release Github Action
    • Follow the release Github Action until successful completion.

Contributing

At DigitalOcean we value and love our community! If you have any issues or would like to contribute, see CONTRIBUTING.md.

License

Copyright 2022 DigitalOcean.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

do-operator's People

Contributors

adamwg avatar dhij avatar gottwald avatar halkeye avatar kperath avatar lldrlove avatar mo-rieger avatar timoreimann avatar varshavaradarajan avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

do-operator's Issues

read-only replicas

It would be nice to be able to create read-only replicas from the operator.

I imagine there would be a "PrimaryClusterId" field in the DatabaseClusterSpec which would, during creation, create a replica.

If this field was deleted down the line, the database could promote itself to a primary.

alternatively, there could be a "DatabaseReplicaCluster". This would involve adding a field like "ReplicaClusterId" in "DatabaseClusterSpec" which would facilitate the promotion & deletion of the old replica.

Add events for DatabaseUsers

When reconciling a DatabaseUser we should create events to show progress - e.g., when we request a user to be created and if any of our actions fail.

The kubebuilder docs show how to create events.

Unable to create a reference - failed calling webhook - how to debug?

Hello.

I am unable to create the cluster reference, please help.

Error from server (InternalError): error when creating "my-db-reference.yaml": Internal error occurred: failed calling webhook "vdatabaseclusterreference.kb.io": failed to call webhook: Post "https://do-operator-webhook-service.do-operator-system.svc:443/validate-databases-digitalocean-com-v1alpha1-databaseclusterreference?timeout=10s": EOF

The namespace I am pointing to is default, as I have:

$ kubectl get namespaces NAME STATUS AGE cert-manager Active 71m default Active 125m do-operator-system Active 17m kube-node-lease Active 125m kube-public Active 125m kube-system Active 125m

It's a brand new terraformed k8s cluster and database cluster.

Add end-to-end application examples in the documentation

It would be great to show some real usage examples in the docs. Ideally we would have examples for both architectures:

  1. Managed architecture - the DB and app are deployed together in one manifest.
  2. Referenced architecture - the DB is created via Terraform and its ID injected into the app manifest before deployment (also via Terraform).

Database CA should be included in credentials secret

Currently the connection details for databases indicate that sslmode should be required. But, as the CA certificate securing these databases is self-signed, doing so properly is not possible without the CA certificate. A user could download this certificate out-of-band from the operator, but doing so is inconvenient and cumbersome.

Where applicable, the operator should include the CA certificate data in the credentials secret.

make undeploy causing do-operator-system namespace stuck Terminating state

What happened?

with kubernetes v1.28.0 i am able to install do-operator successfully by running make deploy but after installation when i run make undeploy terminal stuck and need to manually exit.

Screenshot_20231003_015844

And in cluster that namesapce which is created by do-operator do-operator-system stuck at Terminating state

Screenshot_20231003_020419

By describing the namespace there is one condition because of which the namesapce is not able to delete is NamespaceDeletionContentFailure

Screenshot_20231003_020744

Manually inspecting the cluster i didn't find any resource in do-operator-system namespace. After which i had to manually remove the finalizer from that namespace for its deletion.

Steps to reproduce

  1. kubernetes v1.28
  2. deploy operator using make deploy and after operator is in Running state remove the operator using make undeploy

Expected behavior
Namespace do-operator-system should not stuck in Terminating state when running make undeploy

How to specify a Postgres database other than defaultdb

In a Postgres database cluster we can have multiple databases, e.g. per application/service. By default a cluster is created with a single database called defaultdb, but additional databases can be created via the control panel or doctl.

When using the DatabaseClusterReference I have not found a way to specify a specific database and hence the created configmaps reference defaultdb.

Is there a way to change this?

Validate cluster UUID values

Ensure that any cluster UUID values which can be specified by a human or operator are conformant to the UUID spec. Otherwise, follow-up operations may start to fail in hard-to-debug ways.

The motivation here was a case where a cluster UUID was copied from the cloud control panel with the a query parameter like ?=<id> appended. This would short-circuit HTTP requests to the DO API carried out by godo and not return sub-resources anymore.

Delete never succeeds if you delete an object that would never have formed a cluster

This is the example from the readme. If you apply it, there are errors because num_nodes should be numNodes. If you then delete that object it never gets cleared out. If you manually delete the finalizers from the object using kubectl edit database example then the object clears out immediately.

I think the operator can reject the illegal object before it ever gets into the cluster so maybe this needn't be fixed directly.

apiVersion: doop.do.co/v1alpha1
kind: Database
metadata:
  name: example
spec:
  name: example
  engine: redis
  version: "5"
  size: db-s-2vcpu-4gb
  region: sfo2
  num_nodes: 2
  tags:
  - test
  - doop

Expose uri and private_url for DatabaseUsers

In the default DB credential secret, there are fields for the uri and private_uri of the database, which is helpful to expose as env variables in containers. But these two fields are missing for additional users created via a DatabaseUser. This makes it rather more annoying to get the uri to connect to into an environment variable for a container without also exposing the admin password. (Though you can get the pieces as seperate variables but that may require code changes to our apps if they are expecting a uri.)

Database operator admission webhook is too strict

Currently an attempt to create a DatabaseUser when a cluster resource does not exist results in an error as such:

Error from server (Forbidden): error when creating "sample.yaml": admission webhook "vdatabaseuser.kb.io" denied the request: spec.cluster: Not found: default/my-app-db

While reasonable, it creates issues with automations such as helm/kustomize (and by extension GitOps solutions) because it creates chicken and egg problem between DatabaseCluster and DatabaseUser resource.

If the check, rather than being done during admission, was done by operator itself during resource handling it would allow for the usual Kubernetes eventually consistent workflow with resources at some point arriving at desired state.

Change output of DatabaseClusterReference

Currently a secret is created with the following content:

username: doadmin
password: ....
private_uri: ....
uri: mysql://doadmin:<pass>@<db-server-name>.db.ondigitalocean.com:25060/defaultdb?ssl-mode=REQUIRED

The URI includes the username, password, database. If I want to connect using the credentials of a DatabaseUser I only require the host (similar holds for connecting to a different database).

Suggested output (same as the connection parameters tab, including or excluding uri's):

username: doadmin
password: ...
host: <db-server-name>.db.ondigitalocean.com
private_host: private-<db-server-name>.db.ondigitalocean.com
port: <port>
sslmode: ...

Add events for DatabaseClusters

When reconciling a DatabaseCluster we should create events to show progress - e.g., when we request a DO database to be created, when we check whether it's ready, and if any of our actions fail.

The kubebuilder docs show how to create events.

Support database creation

I'd like to also create databases similar to DatabaseUser resources.

Maybe this is confusing with the 'Database' prefix naming convention. Perhaps it should be 'DatabaseServer' instead so that we can use DatabaseServerDatabase and DatabaseServerUser.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.