Merge ~mthaddon/charm-k8s-bind/+git/charm-k8s-bind:end-user into charm-k8s-bind:master

[Tom Haddon]

Update README and metadata.yaml to be more end-user focused

Update README and metadata.yaml to be more end-user focused

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

This merge proposal is being monitored by mergebot. Change the status to Approved to merge.

[Laurent Sesquès (sajoupa)]

review: Approve

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

Change successfully merged at revision 0a8dd267a40755311d723c4cb8458a59db4f0b45

diff --git a/README.md b/README.md
index 9fc2862..d53b3a5 100644
--- a/README.md
+++ b/README.md
@@ -1,70 +1,37 @@
-# Bind charm
+# Bind Operator
 
 A Juju charm deploying Bind, configurable to use a git repository for its configuration files.
 
 ## Overview
 
-This is a k8s workload charm and can only be deployed to a Juju k8s cloud,
-attached to a controller using `juju add-k8s`.
+BIND 9 has evolved to be a very flexible, full-featured DNS system. Whatever
+your application is, BIND 9 probably has the required features. As the first,
+oldest, and most commonly deployed solution, there are more network engineers
+who are already familiar with BIND 9 than with any other system.
 
-This charm is not currently ready for production due to issues with providing
-an egress to route TCP and UDP traffic to the pods. See:
+## Usage
 
-https://bugs.launchpad.net/charm-k8s-bind/+bug/1889746
-
-https://bugs.launchpad.net/juju/+bug/1889703
-
-## Getting Started
-
-Notes for deploying a test setup locally using microk8s, the setup of which is
-documented here: https://juju.is/docs/microk8s-cloud
-
-```
-juju add-model bind-test
-```
-
-1. Either deploy with the default image from Dockerhub:
+For details on using Kubernetes with Juju [see here](https://juju.is/docs/kubernetes), and for
+details on using Juju with MicroK8s for easy local testing [see here](https://juju.is/docs/microk8s-cloud).
 
+To deploy this charm in a juju k8s model:
 ```
 juju deploy cs:~bind-charmers/bind
 ```
-2. Or optionally build your own image locally and deploy with that
-
-```
-sudo snap install charmcraft
-git clone https://git.launchpad.net/charm-k8s-bind
-cd charm-k8s-bind
-make image-build
-docker push localhost:32000/bind
-juju deploy cs:~bind-charmers/bind --config bind_image_path=localhost:32000/bind:latest bind
-
-juju wait
-juju status
-```
-
-Assuming you're using the image from dockerhub, or an image built locally from
-this repo without changes, the charm will deploy bind with its stock Ubuntu
-package configuration, which will forward all queries to root name servers.
+The charm will deploy bind with its stock Ubuntu package configuration, which
+will forward all queries to root name servers.
 
 DNSSEC is also enabled by default.
 
 Custom config can be deployed by setting the `custom_config_repo` option to
 point to a Git repository containing a valid set of configuration files with
-which to populate the /etc/bind/ directory within the pod(s).
+which to populate the `/etc/bind/` directory within the pod(s).
 
 Since bind won't allow recursion from external clients by default, to allow
-easy testing, I've set up a repo with a copy of the stock config, modified to
-allow recursion from all RFC1918 networks:
-
-https://code.launchpad.net/~barryprice/junk/+git/etc-bind-stock-config-with-all-rfc1918-nets-allowed
-
-To configure a local microk8s-deployed bind application to use this config,
-simply run:
-
+easy testing, you can use [a repo with a copy of the stock config, modified to allow recursion from all RFC1918 networks](https://code.launchpad.net/~barryprice/junk/+git/etc-bind-stock-config-with-all-rfc1918-nets-allowed):
 ```
 juju config bind custom_config_repo=https://git.launchpad.net/~barryprice/junk/+git/etc-bind-stock-config-with-all-rfc1918-nets-allowed
 ```
-
 Once the application is ready, you should be able to query the App's IP address
 (not the Unit addresses) directly from your local machine:
 
@@ -84,3 +51,9 @@ $ dig +short example.com @10.152.183.246
 93.184.216.34
 $
 ```
+
+## Known Issues
+
+This charm is unable to provide an ingress to route TCP and UDP traffic to the
+pods due to [LP#1889703](https://bugs.launchpad.net/juju/+bug/1889703). This is
+also being tracked as [a bug against the charm itself](https://bugs.launchpad.net/charm-k8s-bind/+bug/1889746).
diff --git a/metadata.yaml b/metadata.yaml
index 12075b3..7b1d7b2 100644
--- a/metadata.yaml
+++ b/metadata.yaml
@@ -1,6 +1,9 @@
-name: "bind"
-summary: "Bind"
-description: "The original, complete open source DNS implementation"
+name: bind
+summary: The original, complete open source DNS implementation.
+docs: https://discourse.charmhub.io/t/bind-documentation-overview/3973
+description: |
+  The original, complete open source DNS implementation.
+  https://www.isc.org/bind/
 min-juju-version: 2.8.0
 maintainers:
   - https://launchpad.net/~bind-charmers <[e-mail]>