bind-charmers team mailing list archive

[Tom Haddon <tom.haddon@xxxxxxxxxxxxx>]

Tom Haddon has proposed merging ~mthaddon/charm-k8s-bind/+git/charm-k8s-bind:readme into charm-k8s-bind:master.

Commit message:
Update README based on Discourse post with more user-friendly intro

Requested reviews:
  Bind Charmers (bind-charmers)

For more details, see:
https://code.launchpad.net/~mthaddon/charm-k8s-bind/+git/charm-k8s-bind/+merge/394896

Update README based on Discourse post with more user-friendly intro
-- 
Your team Bind Charmers is requested to review the proposed merge of ~mthaddon/charm-k8s-bind/+git/charm-k8s-bind:readme into charm-k8s-bind:master.

diff --git a/README.md b/README.md
index c0b037d..1c0b09c 100644
--- a/README.md
+++ b/README.md
@@ -4,22 +4,35 @@ A Juju charm deploying Bind, configurable to use a git repository for its config
 
 ## 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`.
+You can deploy it locally in MicroK8s and then use the local service IP to
+resolve DNS queries like this, assuming you've already set up [a local single-node microk8s Juju controller](https://juju.is/docs/microk8s-cloud)
+and have created a juju k8s model:
 
-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:
+    $ juju deploy cs:~bind-charmers/bind
+    $ juju status
+    Model      Controller       Cloud/Region     Version  SLA          Timestamp
+    bind-test  myk8s-localhost  myk8s/localhost  2.8.6    unsupported
+    16:13:23+07:00
 
-https://bugs.launchpad.net/charm-k8s-bind/+bug/1889746
+    App   Version    Status  Scale  Charm  Store       Rev  OS          Address         Notes
+    bind  bind:edge  active      1  bind   jujucharms    1  kubernetes  10.152.183.246
 
-https://bugs.launchpad.net/juju/+bug/1889703
+    Unit     Workload  Agent  Address     Ports          Message
+    bind/0*  active    idle   10.1.25.13  53/TCP,53/UDP  Pod configured
 
-## Details
+However, we don't yet have a user-friendly method to expose such a service to
+the internet, e.g. from a Juju-deployed Kubernetes cluster (see [Launchpad bug LP#1889703](https://bugs.launchpad.net/juju/+bug/1889703) to track that feature request).
 
-See config option descriptions in config.yaml.
+Deployed with the default settings, the charm will install and configure bind
+with the default Ubuntu package configuration, so DNSSEC enabled, with no
+forwarders explicitly defined - it'll use the root nameservers, so will need
+to be able to reach those.
 
-## Getting Started
+Any manner of custom configuration is supported by simply configuring the
+charm with the location of a git repository with which to populate `/etc/bind/`,
+for example:
 
+<<<<<<< README.md
 Notes for deploying a test setup locally using microk8s, the setup of which is
 documented here: https://juju.is/docs/microk8s-cloud
 
@@ -49,6 +62,73 @@ 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.
+=======
+    juju config bind custom_config_repo="https://github.com/example/custom-bind-config";
+
+The charm currently neither requires nor supports any relations.
+
+Because bind's default settings don't allow recursive queries by default,
+you'll need to change that with a custom config if you want to be able to run
+test queries from your local machine. So in a MicroK8s setup on a laptop or
+workstation, once you've deployed the charm as above, feel free to use this
+public repository which just contains the stock bind config from the Ubuntu
+20.04 package, with a 1-line change to allow all RFC1918 networks to query the
+application - this obviously isn't designed for a production environment, but
+just to allow simple testing:
+
+    juju config bind custom_config_repo="https://git.launchpad.net/~barryprice/junk/+git/etc-bind-stock-config-with-all-rfc1918-nets-allowed";
+
+And once that's settled:
+
+    $ juju status
+    Model      Controller       Cloud/Region     Version  SLA          Timestamp
+    bind-test  myk8s-localhost  myk8s/localhost  2.8.6    unsupported  16:55:23+07:00
+
+    App   Version    Status  Scale  Charm  Store       Rev  OS          Address        Notes
+    bind  bind:edge  active      1  bind   jujucharms    2  kubernetes  10.152.183.246
+
+    Unit     Workload  Agent  Address     Ports          Message
+    bind/1*  active    idle   10.1.25.36  53/TCP,53/UDP
+    $ dig +short example.com @10.152.183.246
+    93.184.216.34
+    $ dig +short example.com @10.152.183.246 AAAA
+    2606:2800:220:1:248:1893:25c8:1946
+    $ dig +short +dnssec example.com @10.152.183.246
+    93.184.216.34
+    A 8 2 86400 20201115051118 20201025154454 62811 example.com. P8BE247EZ54+DZ1aZOVDYv3MxnxT+XAmd1W41PyBCB0QopMxAe7l6brVVXQtfDwsY6wL71BKZL7eTsyWYP9x4JQTYeY6UIwXeuOQ+uS8A+fGlQBaaPCIZCw0JQQTCCmCmmrrwpkIDAiunF0UOeRZl3CzE5QOX0lw4db/3M6n IKg=
+    $
+
+## Local Development
+
+Notes for deploying a test setup locally using MicroK8s:
+
+    sudo snap install juju --classic
+    sudo snap install juju-wait --classic
+    sudo snap install microk8s --classic
+    sudo snap alias microk8s.kubectl kubectl
+    sudo snap install charmcraft
+    git clone https://git.launchpad.net/charm-k8s-bind
+    make bind.charm
+
+    microk8s.reset  # Warning! Clean slate!
+    microk8s.enable dns dashboard registry storage
+    microk8s.status --wait-ready
+    microk8s.config | juju add-k8s myk8s --client
+
+    # Build your Bind image
+    make build-image
+    docker push localhost:32000/bind
+    
+    juju bootstrap myk8s
+    juju add-model bind-test
+    juju deploy ./bind.charm --config bind_image_path=localhost:32000/bind:latest bind
+    juju wait
+    juju status
+
+Assuming you're using the image as built locally from this repo, the charm will
+deploy bind with its stock Ubuntu package configuration, which will forward all
+queries to root name servers.
+>>>>>>> README.md
 
 DNSSEC is also enabled by default.