Added Basic Charm

.github/workflows/ci.yaml

@@ -1,5 +1,9 @@
 name: Tests
-on: [pull_request, push]
+on:
+  push:
+    branches:
+      - main
+    pull_request:
 
 jobs:
   lint:
@@ -39,6 +43,5 @@ jobs:
         uses: canonical/charm-logdump-action@main
         if: failure()
         with:
-          # TEMPLATE-TODO: Replace the application name
-          app: operator-template
+          app: pgbouncer-k8s-operator
           model: itest

CONTRIBUTING.md

@@ -5,27 +5,39 @@
 This documents explains the processes and practices recommended for contributing enhancements to
 this operator.
 
-<!-- TEMPLATE-TODO: Update the URL for issue creation -->
-
 - Generally, before developing enhancements to this charm, you should consider [opening an issue
-  ](https://github.com/canonical/operator-template/issues) explaining your use case.
+  ](https://github.com/canonical/pgbouncer-k8s-operator/issues) explaining your use case.
 - If you would like to chat with us about your use-cases or proposed implementation, you can reach
   us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev)
   or [Discourse](https://discourse.charmhub.io/).
 - Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library
   will help you a lot when working on new features or bug fixes.
-- All enhancements require review before being merged. Code review typically examines
+- All enhancements require at least 2 approving reviews before being merged. Code review typically examines
   - code quality
   - test coverage
   - user experience for Juju administrators this charm.
 - Please help us out in ensuring easy to review branches by rebasing your pull request branch onto
   the `main` branch. This also avoids merge commits and creates a linear Git commit history.
 
-## Developing
+## Environment Setup
 
-You can use the environments created by `tox` for development:
+This setup is required for testing and deploying this charm. These instructions are written assuming you're using microk8s as your juju substrate. Instructions for setting this up can be found [here](https://juju.is/docs/olm/microk8s). If you're using a different substrate, update these instructions accordingly.
 
 ```shell
+# Import container
+git clone https://github.com/canonical/pgbouncer-container.git
+# Build container locally, since it's not been exported anywhere yet.
+docker build . -t pgbouncer:0.8
+docker save pgbouncer:0.8 -o pgb.tar
+# Import container file into microk8s container registry
+microk8s ctr image import pgb.tar
+
+# Create a model
+juju add-model dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+
+# initialise an environment using tox
 tox --notest -e unit
 source .tox/unit/bin/activate
 ```
@@ -50,14 +62,11 @@ charmcraft pack
 
 ### Deploy
 
-<!-- TEMPLATE-TODO: Update the deploy command for name of charm-->
-
 ```bash
-# Create a model
-juju add-model dev
-# Enable DEBUG logging
-juju model-config logging-config="<root>=INFO;unit=DEBUG"
-# Deploy the charm
-juju deploy ./template-operator_ubuntu-20.04-amd64.charm \
-    --resource httpbin-image=kennethreitz/httpbin \
+juju deploy ./pgbouncer-k8s-operator_ubuntu-20.04-amd64.charm \
+    --resource pgbouncer-image=pgbouncer:0.8
 ```
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the Charmed PGBouncer Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

README.md

@@ -1,23 +1,64 @@
-# operator-template
+# PgBouncer Kubernetes Operator
 
 ## Description
 
-TODO: Describe your charm in a few paragraphs of Markdown
+The PgBouncer Kubernetes Operator deploys and operates the [PgBouncer](https://www.pgbouncer.org) lightweight connection pooler for PostgreSQL.
 
 ## Usage
 
-TODO: Provide high-level usage, such as required config or relations
+As this charm is not yet published, you need to follow the build and deploy instructions from [CONTRIBUTING.md](https://github.com/canonical/pgbouncer-k8s-operator/CONTRIBUTING.md).
+
+## Actions
+
+- `reload-pgbouncer`
+  - Reloads the pgbouncer application.
+  - Currently only implemented as a stub.
+- `add-user`
+  - Adds a new pgbouncer user.
+  - Params:
+    - username
+    - password
+- `remove-user`
+  - Removes an existing pgbouncer user.
+  - Params:
+    - username
+- `change-password`
+  - Updates the password for a given pgbouncer user.
+  - Params:
+    - username
+    - password
+- `get-users`
+  - Lists the existing pgbouncer users.
 
 ## Relations
 
-TODO: Provide any relations which are provided or required by your charm
+### Planned
+
+- `db:`[`pgsql`](https://github.com/canonical/ops-lib-pgsql/)
+- `db-admin:`[`pgsql`](https://github.com/canonical/ops-lib-pgsql/)
+- `backend-db-admin:`[`pgsql`](https://github.com/canonical/ops-lib-pgsql/)
+  - Provides a relation to the corresponding [postgresql-k8s-operator charm](https://github.com/canonical/postgresql-k8s-operator).
+
+The following relations provide support for the [LMA charm bundle](https://juju.is/docs/lma2), our expected observability stack.
+
+- `prometheus:prometheus_scrape`
+- `loki:loki_push_api`
+- `grafana:grafana_dashboards`
 
 ## OCI Images
 
-TODO: Include a link to the default image your charm uses
+This charm uses the canonical pgbouncer-container docker image, available [here](https://github.com/canonical/pgbouncer-container). As this container has not been uploaded anywhere, **you will need to build this image locally and import it into your container registry before use**, following the instructions in [CONTRIBUTING.md]([CONTRIBUTING.md](https://github.com/canonical/pgbouncer-k8s-operator/CONTRIBUTING.md)).
+
+## License
+
+The Charmed PgBouncer Operator is free software, distributed under the Apache Software License, version 2.0. See [LICENSE](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/LICENSE) for more information.
+
+## Security
+
+Security issues in the Charmed PgBouncer Operator can be reported through [LaunchPad](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File). Please do not file GitHub issues about security issues.
 
 ## Contributing
 
 Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines
 on enhancements to this charm following best practice guidelines, and
-[CONTRIBUTING.md](./CONTRIBUTING.md) for developer guidance.
+[CONTRIBUTING.md](https://github.com/canonical/pgbouncer-k8s-operator/CONTRIBUTING.md) for developer guidance.

actions.yaml

@@ -1,16 +1,38 @@
 # Copyright 2021 Canonical Ltd.
 # See LICENSE file for licensing details.
-#
-# TEMPLATE-TODO: change this example to suit your needs.
-# If you don't need actions, you can remove the file entirely.
-# It ties in to the example _on_fortune_action handler in src/charm.py
-#
-# Learn more about actions at: https://juju.is/docs/sdk/actions
 
-fortune:
-  description: Returns a pithy phrase.
+reload-pgbouncer:
+  description: Reloads pgbouncer application. This does not restart the container.
+
+add-user:
+  description: Adds a new pgbouncer user.
+  params:
+    username:
+      type: string
+      description: The username of the given user. If a user exists by this name, this action will fail.
+    password:
+      type: string
+      description: The password of the given user
+  required: [username, password]
+
+remove-user:
+  description: Removes pgbouncer user. NB this can only remove users added through the `add-user` action; users added using the charm config must be removed from the config, and through this action.
   params:
-    fail:
-      description: "Fail with this message"
+    username:
       type: string
-      default: ""
+      description: The username of the given user. If a user by this name does not exist, this action will fail.
+  required: [username]
+
+change-password:
+  description: Changes password for a given user.
+  params:
+    username:
+      type: string
+      description: Username of an existing user
+    password:
+      type: string
+      description: The new password
+  required: [username, password]
+
+get-users:
+  description: Lists all pgbouncer users.

charmcraft.yaml

@@ -9,6 +9,7 @@ bases:
     run-on:
       - name: "ubuntu"
         channel: "20.04"
+
 parts:
   charm:
     build-packages:

config.yaml

@@ -1,14 +1,23 @@
 # Copyright 2021 Canonical Ltd.
 # See LICENSE file for licensing details.
-#
-# TEMPLATE-TODO: change this example to suit your needs.
-# If you don't need a config, you can remove the file entirely.
-# It ties in to the example _on_config_changed handler in src/charm.py
-#
-# Learn more about config at: https://juju.is/docs/sdk/config
 
 options:
-  thing:
-    default: 🎁
-    description: A thing used by the charm.
-    type: string
+  pgb_databases:
+    default: "exampledb = host=pg-host port=5432 dbname=exampledb"
+    description: "multiline string containing database config (one per line)."
+    type: "string"
+
+  pgb_listen_port:
+    default: 6432
+    description: "Port on which PGBouncer listens for traffic"
+    type: "int"
+
+  pgb_listen_address:
+    default: "localhost"
+    description: "Address on which PGBouncer listens for traffic"
+    type: "string"
+
+  pgb_admin_users:
+    default: "juju-admin"
+    description: "A comma-separated list of admin users. A password will be generated for each user. Only generates `juju-admin` user by default"
+    type: "string"

metadata.yaml

@@ -1,25 +1,24 @@
 # Copyright 2021 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-# For a complete list of supported options, see:
-# https://discourse.charmhub.io/t/charm-metadata-v2/3674/15
-name: operator-template
+name: pgbouncer-k8s-operator
 display-name: |
-  TEMPLATE-TODO: fill out a display name for the Charmcraft store
+  PgBouncer Kubernetes Operator
 description: |
-  TEMPLATE-TODO: fill out the charm's description
+  Lightweight connection pooler for PostgreSQL.
 summary: |
-  TEMPLATE-TODO: fill out the charm's summary
+  The aim of pgbouncer is to lower the performance impact of opening new connections to PostgreSQL. For more information, see https://www.pgbouncer.org/usage.html
+maintainers:
+  "Will Fitch <will.fitch@canonical.com>"
 
-# TEMPLATE-TODO: replace with containers for your workload (delete for non-k8s)
 containers:
-  httpbin:
-    resource: httpbin-image
+  pgbouncer:
+    resource: pgbouncer-image
 
-# TEMPLATE-TODO: each container defined above must specify an oci-image resource
 resources:
-  httpbin-image:
+  pgbouncer-image:
     type: oci-image
-    description: OCI image for httpbin (kennethreitz/httpbin)
-    # Included for simplicity in integration tests
-    upstream-source: kennethreitz/httpbin
+    description: OCI image for pgbouncer
+    # currently this uses a local build of https://github.com/canonical/pgbouncer-container - see CONTRIBUTING.md for instructions.
+    upstream-source: pgbouncer:0.8
+    local-source: pgbouncer:0.8

requirements.txt

@@ -1 +1 @@
-ops >= 1.2.0
+ops >= 1.3.0