Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/prometheus:readme-template into ~ubuntu-docker-images/ubuntu-docker-images/+git/prometheus:edge

[Lucas Kanashiro]

Make OCI doc files compliance with the defined template.

[Sergio Durigan Junior (sergiodj)]

Thanks, Lucas. Just needs a few minor adjustments and it'll be good to go.

review: Needs Fixing

[Lucas Kanashiro (lucaskanashiro)]

Comments addressed, I am going to merge it.

review: Approve

diff --git a/oci/README.md b/oci/README.md
index e5d8126..5679e90 100644
--- a/oci/README.md
+++ b/oci/README.md
@@ -1,66 +1,152 @@
-# Ubuntu Prometheus OCI image
+# Prometheus | Ubuntu
 
-This OCI image was built based on the upstream one (prom/prometheus). Prometheus in Ubuntu is supported as a snap package, so both are built from the same source. The Ubuntu Dockerfile differs a bit from upstream, instead of relying on the upstream Makefile to do the build and copy the binaries and needed file into the image, we do the build and test of the code during OCI build time.
+## About Prometheus
 
-As an initial attempt to not require Internet access to build the image the following was changed:
+Prometheus is a systems and service monitoring system. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts if some condition is observed to be true. Read more on the [Prometheus website](https://prometheus.io/).
 
-* Add the promu (tool used to build prometheus) binaries for the supported architectures to this repo to avoid downloading them from Github. Build promu from source was also considerd but it depends on itself (older version) to build, for now the binaries built from upstream are used.
+## Tags
 
-There is no change that should impact users.
-
-## Versions supported
-
-* `edge` = `2.20.1`
+* `2.20.1`, `2.20`, `2`, `beta` - **/!\ this is a beta release**
 
 ## Architectures supported
 
-* amd64
-* arm64
-* ppc64el
-* s390x
+* `amd64`, `arm64`, `ppc64el`, `s390x`
 
 ## Usage
 
-To get this image run:
+### Docker CLI
 
-```
-$ docker pull squeakywheel/prometheus:edge
+```sh
+$ docker run --name prometheus -e TZ=UTC -d squeakywheel/prometheus:edge
 ```
 
-Prometheus command line can be called like this:
+Since containers are ephemeral, you may want to use persistent data rather than initializing a new database for each newly launched container.  To do this, you can use docker volumes:
 
+```sh
+$ docker run --name prometheus -v /path/to/persisted/data:/prometheus -e TZ=UTC -d squeakywheel/prometheus:edge
 ```
-$ docker run squeakywheel/prometheus:edge -h
-```
 
-The command above will display the output of the `prometheus -h`.
+**Important note**: the directory you will be using to persist the data needs to belong to `nogroup:nobody`. You can run `chown nogroup:nobody <path_to_persist_data>` before launching your container.
+
+#### Parameters
+
+| Parameter | Description |
+|---|---|
+| `-e TZ=UTC` | Timezone. |
+| `-v /path/to/persisted/data:/prometheus` | Pass the directory used to persist the data. |
+| `-v /path/to/prometheus/config/file/prometheus.yml:/etc/prometheus/prometheus.yml` | Pass a custom config file. |
+| `-v /path/to/prometheus/config/file/alerts.yml:/etc/prometheus/alerts.yml` | Pass a custom alerts config file. |
+
+
+#### Testing/Debugging
 
-Since containers are ephemeral you might be interested in persist data and not initialize a new TSDB database every time you launch a new container. To do that you can use docker volumes:
+In case you need to debug what it is happening with the container you can run `docker logs <name_of_the_container>`. To get access to an interactive shell run:
 
 ```
-$ docker run --name prometheus \
-             --volume /path/to/persisted/data:/prometheus \
-             squeakywheel/prometheus:edge
+$ docker exec -it <name_of_the_container> /bin/bash
 ```
 
-Important note: the directory you will be using to persist the data needs to belong to `nogroup:nobody`. You can run `chown nogroup:nobody <path_to_persist_data>` before launching your container.
+### Deploy with Kubernetes
+
+You can use your favorite Kubernetes distribution; if you don't have one, consider [installing MicroK8s](https://microk8s.io/).
 
-You can also pass your own configuration files to the container doing the following:
+With microk8s running, enable the `dns` and `storage` add-ons:
+```sh
+$ microk8s enable dns storage
+ ```
 
+Create a configmap for the configuration files (check the upstream documentation [here](https://prometheus.io/docs/prometheus/2.20/getting_started/)):
+
+```sh
+$ microk8s kubectl create configmap prometheus-config --from-file=prometheus=config/prometheus.yml --from-file=prometheus-alerts=config/alerts.yml
 ```
-$ docker run --name prometheus \
-             --volume /path/to/prometheus/config/file/prometheus.yml:/etc/prometheus/prometheus.yml
-             --volume /path/to/prometheus/config/file/alerts.yml:/etc/prometheus/alerts.yml
-             squeakywheel/prometheus:edge
+
+Use the sample deployment yaml provided [here](https://git.launchpad.net/~canonical-server/ubuntu-server-oci/+git/prometheus/plain/examples/prometheus-deployment.yml).
+
+<details>
+  <summary>Apply the `prometheus-deployment.yml` (click to expand)</summary>
+
+```yaml
+# prometheus-deployment.yml
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: prometheus-volume-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 500M
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: prometheus-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: prometheus
+  template:
+    metadata:
+      labels:
+        app: prometheus
+    spec:
+      containers:
+      - name: prometheus
+        image: squeakywheel/prometheus:edge
+        volumeMounts:
+        - name: prometheus-config-volume
+          mountPath: /etc/prometheus/prometheus.yml
+          subPath: prometheus.yml
+        - name: prometheus-config-volume
+          mountPath: /etc/prometheus/alerts.yml
+          subPath: alerts.yml
+        - name: prometheus-data
+          mountPath: /prometheus
+        ports:
+        - containerPort: 9090
+          name: prometheus
+          protocol: TCP
+      volumes:
+        - name: prometheus-config-volume
+          configMap:
+            name: prometheus-config
+            items:
+            - key: prometheus
+              path: prometheus.yml
+            - key: prometheus-alerts
+              path: alerts.yml
+        - name: prometheus-data
+          persistentVolumeClaim:
+            claimName: prometheus-volume-claim
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: prometheus-service
+spec:
+  type: NodePort
+  selector:
+    app: prometheus
+  ports:
+  - protocol: TCP
+    port: 9090
+    targetPort: 9090
+    nodePort: 30090
+    name: prometheus
 ```
 
-In case you need to debug what it is happening with the container you can run `docker logs <name_of_the_container>`. But if you want to get access to an interactive shell run:
+</details>
 
-```
-$ docker exec -it <name_of_the_container> /bin/bash
+```sh
+$ microk8s kubectl apply -f prometheus-deployment.yml
 ```
 
-To see how to use the Prometheus OCI image with `docker-compose` and `microk8s` check the `examples/README.md` file.
+You will now be able to connect to the Prometheus on `http://localhost:30090`.
 
 ## Bugs and Features request
 
@@ -72,6 +158,9 @@ In the title of the bug add `prometheus: <reason>`.
 
 Make sure to include:
 
-* The tag of the image you are using
+* The digest of the image you are using, you can find it using this command replacing `<tag>` with the one you used to run the image:
+```sh
+$ docker images --no-trunc --quiet squeakywheel/prometheus:<tag>
+```
 * Reproduction steps for the deployment
 * If it is a feature request, please provide as much detail as possible
diff --git a/oci/examples/README.md b/oci/examples/README.md
index 9377185..eed65b5 100644
--- a/oci/examples/README.md
+++ b/oci/examples/README.md
@@ -36,10 +36,10 @@ $ microk8s kubectl create configmap prometheus-config \
 		--from-file=prometheus-alerts=config/alerts.yml
 ```
 
-Apply the `microk8s-deployments.yml`:
+Apply the `prometheus-deployment.yml`:
 
 ```
-$ microk8s kubectl apply -f microk8s-deployments.yml
+$ microk8s kubectl apply -f prometheus-deployment.yml
 ```
 
 Access `http://localhost:30090` and Prometheus will be running.
diff --git a/oci/examples/microk8s-deployments.yml b/oci/examples/prometheus-deployment.yml
similarity index 100%
rename from oci/examples/microk8s-deployments.yml
rename to oci/examples/prometheus-deployment.yml