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

[Tom Haddon]

Update README to be more end-user focused, and point to discourse-based docs for more information

Update README to be more end-user focused, and point to discourse-based docs for more information

[James Troup (elmo)]

Couple of high level comments and then some inline.

 1) I think there should be more prominence given to the fact that this cache is nginx powered? For better or worse, it's a globally recognised brand, we should trade on it.

 2) the updated README leads with our use case. I think you should lead with an example use case, and use our story later as evidence of this charms cachet (sorry, pun not intended but gleefully used)

[Tom Haddon (mthaddon)]

PTAL

[James Troup (elmo)]

Some comments inline, but in general, this LGTM and is definitely an improvement.

review: Approve

[Tom Haddon (mthaddon)]

Thanks for the feedback, all good comments.

Have tried using archive.local for "site" and "juju-external-hostname" but it's not quite working as expected. https://paste.ubuntu.com/p/k4Jgkpy24S/ is what I tried, but this gives me the following in nginx config:

proxy_set_header Host "archive.local";

This means the resources I was requesting previously don't exist (instead I see https://paste.ubuntu.com/p/jg3fjfJsky/ at the site root). Will ask for some feedback from Haw on this and figure out what's needed.

[Haw Loeung (hloeung)]

Okay, fixed in https://code.launchpad.net/~hloeung/charm-k8s-content-cache/+git/charm-k8s-content-cache/+merge/395576

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

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

[Haw Loeung (hloeung)]

LGTM

review: Approve (+1)

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

Change successfully merged at revision 24de1bd9dc1d30f98ede2490e7efd778221013f6

diff --git a/README.md b/README.md
index ddca31c..6d9b631 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,66 @@
-# charm-k8s-content-cache
+# Content Cache Operator
 
-## Description
+A Juju charm for deploying and managing a content cache.
 
-Deploy content caching layer into K8s.
+## Overview
 
-## Usage
-
-To deploy this charm into a k8s model:
-
-    juju deploy cs:~content-cache-charmers/content-cache-k8s --config site=mysite.local --config backend=http://mybackend.local:80
-
-And then you can test the deployment with:
+A service for caching content, built on top of [Nginx](https://www.nginx.com/)
+configurable to cache any http or https web site. Tuning options include
+cache storage size, maximum request size to cache and cache validity duration.
 
-    curl --resolve mysite.local:80:<ingress IP> http://mysite.local
+This service was developed to provide front-end caching for web sites run by
+Canonical's IS team, and to reduce the need for third-party CDNs by providing
+high-bandwidth access to web sites via this caching front-end. Currently used
+for a number of services including [the Snap Store](https://snapcraft.io/store),
+the majority of Canonical's web properties including [ubuntu.com](https://ubuntu.com) and
+[canonical.com](https://canonical.com), and [Ubuntu Extended Security Maintenance](https://ubuntu.com/security/esm).
 
-### Scale Out Usage
+This Kubernetes-based version is built using the same approach, and can be
+used as a front-end caching service in a situation where your Kubernetes
+cluster and its ingress controllers have a fast connection to the Internet.
 
-Just run `juju scale-application <application name> 3`.
-
-## Using a Custom Image
-
-Build the docker image:
+## Usage
 
-    git clone https://git.launchpad.net/charm-k8s-content-cache
-    cd charm-k8s-content-cache/docker
-    docker build . -t myimage:v<revision>
-    docker tag myimage:v<revision> localhost:32000/myimage:v<revision>
-    docker push localhost:32000/myimage:v<revision>
+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).
 
-Then, to use your new image, either replace the `deploy` step above with
+To deploy this charm into a k8s model, with sample configuration set up to
+cache `archive.ubuntu.com` on `archive.local`:
 
-    juju deploy cs:~content-cache-charmers/content-cache-k8s --config image_path=localhost:32000/myimage:v<revision> --config site=mysite.local --config backend=http://mybackend.local:80
+    juju deploy cs:~content-cache-charmers/content-cache-k8s \
+        --config site=archive.local \
+        --config backend=http://archive.ubuntu.com:80 \
+        --config juju-external-hostname=archive.local
+    juju expose content-cache
 
-Or, if you have already deployed content-cache:
+And then you can test the deployment with:
 
-    juju config content-cache image_path=localhost:32000/myimage:v<revision>
+    # Set this to to the "Address" value in the "App" section of `juju status`
+    APP_IP=10.152.183.117
 
-## Developing
+First let's request a resource with headers that will allow us to cache (with
+sample output):
 
-To build the charm locally, just run `charmcraft build`. You can then deploy
-using:
+    curl -v --resolve archive.local:80:${APP_IP} http://archive.local/ubuntu/dists/focal/Contents-i386.gz -o /dev/null 2>&1 | grep 'X-Cache-Status'
+    # < X-Cache-Status: MISS from juju-87625f-hloeung-13 (content-cache-56bbcd79d6-h8dk2)
+    #  First result is a cache MISS
+    curl -v --resolve archive.local:80:${APP_IP} http://archive.local/ubuntu/dists/focal/Contents-i386.gz -o /dev/null 2>&1 | grep 'X-Cache-Status'
+    # < X-Cache-Status: HIT from juju-87625f-hloeung-13 (content-cache-56bbcd79d6-h8dk2)
+    #  Second result is a cache HIT
 
-    juju deploy ./content-cache.charm
+And now let's request a resource which has headers telling us not to cache:
 
-To run lint against the code, run `make lint`.
+    # Verify cache control headers on the upstream resource
+    curl -v http://archive.ubuntu.com/ubuntu/dists/focal/Release 2>&1 | grep 'Cache-Control'
+    #   output: < Cache-Control: max-age=0, proxy-revalidate
+    # And now perform the requests through the content-caching service
+    curl -v --resolve archive.local:80:${APP_IP} http://archive.local/ubuntu/dists/focal/Release -o /dev/null 2>&1 | grep 'X-Cache-Status'
+    # < X-Cache-Status: MISS from juju-87625f-hloeung-13 (content-cache-56bbcd79d6-h8dk2)
+    #  First result is a cache MISS
+    curl -v --resolve archive.local:80:${APP_IP} http://archive.local/ubuntu/dists/focal/Release -o /dev/null 2>&1 | grep 'X-Cache-Status'
+    # < X-Cache-Status: MISS from juju-87625f-hloeung-13 (content-cache-56bbcd79d6-h8dk2)
+    #  Second result still a cache MISS
 
-## Testing
+---
 
-Just run `make unittest`.
+For more details, [see here](https://charmhub.io/content-cache)
diff --git a/metadata.yaml b/metadata.yaml
index dacd17e..7facfdc 100644
--- a/metadata.yaml
+++ b/metadata.yaml
@@ -1,8 +1,8 @@
 name: content-cache
 description: |
-  Useful for providing local mirrors of HTTP servers and building
-  content delivery networks (CDN).
+  A service providing local caches of HTTP servers and useful for building content delivery networks (CDN).
 summary: |
-  Content caching charm for Kubernetes
+  A service providing local caches of HTTP servers and useful for building content delivery networks (CDN).
+docs: https://discourse.charmhub.io/t/content-cache-documentation-overview/3992
 series: [kubernetes]
 min-juju-version: 2.8.0  # charm storage in state