Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/prometheus-alertmanager:readme-template into ~ubuntu-docker-images/ubuntu-docker-images/+git/prometheus-alertmanager: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 715fd2e..8367dc5 100644
--- a/oci/README.md
+++ b/oci/README.md
@@ -1,65 +1,145 @@
-# Ubuntu Prometheus Alertmanager OCI image
+# Prometheus Alertmanager | Ubuntu
 
-This OCI image was built based on the upstream one (prom/alertmanager). Alertmanager 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 Alertmanager
 
-As an initial attempt to not require Internet access to build the image the following was changed:
+The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts. Read more on the [Prometheus Alertmanager website](https://prometheus.io/docs/alerting/latest/alertmanager/).
 
-* 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` = `0.21.0`
+* `0.21.0`, `0.21`, `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-alertmanager:edge
+```sh
+$ docker run --name alertmanager -e TZ=UTC -d squeakywheel/prometheus-alertmanager:edge
 ```
 
-The prometheus-alertmanager OCI image contains the `amtool` tool that you can call it:
+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 alertmanager -v /path/to/persisted/data:/alertmanager -e TZ=UTC -d squeakywheel/prometheus-alertmanager:edge
 ```
-$ docker run --entrypoint "/bin/amtool" squeakywheel/prometheus-alertmanager:edge -h
-```
 
-Pay attention that the default entrypoint is the `alertmanager` binary and not `amtool`, then we need to define it as a new entrypoint. The command above will display the output of the `amtool -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:/alertmanager` | Pass the directory used to persist the data. |
+| `-v /path/to/alertmanager/config/file/alertmanager.yml:/etc/prometheus/alertmanger.yml` | Pass a custom config file. |
+
+#### Testing/Debugging
 
-Since containers are ephemeral you might be interested in persist data and not loose them 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 alertmanager \
-             --volume /path/to/persisted/data:/alertmanager \
-             squeakywheel/prometheus-alertmanager: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 file 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 file (check the upstream documentation [here](https://prometheus.io/docs/alerting/latest/configuration/)):
+
+```sh
+$ microk8s kubectl create configmap alertmanager-config --from-file=alertmanager=config/alertmanager.yml
 ```
-$ docker run --name alertmanager \
-             --volume /path/to/alertmanager/config/file/alertmanager.yml:/etc/prometheus/alertmanager.yml
-             squeakywheel/prometheus-alertmanager:edge
+
+Use the sample deployment yaml provided [here](https://git.launchpad.net/~canonical-server/ubuntu-server-oci/+git/prometheus-alertmanager/plain/examples/prometheus-alertmanager-deployment.yml).
+
+<details>
+  <summary>Apply the `prometheus-alertmanager-deployment.yml` (click to expand)</summary>
+
+```yaml
+# prometheus-alertmanager-deployment.yml
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: alertmanager-volume-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 500M
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: alertmanager-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: alertmanager
+  template:
+    metadata:
+      labels:
+        app: alertmanager
+    spec:
+      containers:
+      - name: alertmanager
+        image: squeakywheel/prometheus-alertmanager:edge
+        volumeMounts:
+        - name: alertmanager-config-volume
+          mountPath: /etc/alertmanager/alertmanager.yml
+          subPath: alertmanager.yml
+        - name: alertmanager-data
+          mountPath: /alertmanager
+        ports:
+        - containerPort: 9093
+          name: alertmanager
+          protocol: TCP
+      volumes:
+        - name: alertmanager-config-volume
+          configMap:
+            name: alertmanager-config
+            items:
+            - key: alertmanager
+              path: alertmanager.yml
+        - name: alertmanager-data
+          persistentVolumeClaim:
+            claimName: alertmanager-volume-claim
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: alertmanager-service
+spec:
+  type: NodePort
+  selector:
+    app: alertmanager
+  ports:
+  - protocol: TCP
+    port: 9093
+    targetPort: 9093
+    nodePort: 30093
+    name: alertmanager
 ```
 
-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-alertmanager-deployment.yml
 ```
 
-To see how to use the Alertmanager 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:30093`.
 
 ## Bugs and Features request
 
@@ -71,6 +151,9 @@ In the title of the bug add `prometheus-alertmanager: <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-alertmanager:<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 d1d358d..7d7bc35 100644
--- a/oci/examples/README.md
+++ b/oci/examples/README.md
@@ -35,10 +35,10 @@ $ microk8s kubectl create configmap alertmanager-config \
 	--from-file=alertmanager=config/alertmanager.yml
 ```
 
-Apply the `microk8s-deployments.yml`:
+Apply the `prometheus-alertmanager-deployment.yml`:
 
 ```
-$ microk8s kubectl apply -f microk8s-deployments.yml
+$ microk8s kubectl apply -f prometheus-alertmanager-deployment.yml
 ```
 
 Access `http://localhost:30093` and Alertmanager will be running.
diff --git a/oci/examples/microk8s-deployments.yml b/oci/examples/prometheus-alertmanager-deployment.yml
similarity index 100%
rename from oci/examples/microk8s-deployments.yml
rename to oci/examples/prometheus-alertmanager-deployment.yml