Merge branch 'update-docs' into 'master'

Update docs

See merge request !18

README.md

@@ -64,6 +64,24 @@ ssh -J ubuntu@<bastion_ip_address> ubuntu@<control-node_ip_address>
 sudo -i
 kubectl get nodes
 ```
+## Monitoring
+To apply monitoring stack you need to switch <code>install_monitoring_task: true</code>, located at <code>[ansible/group_vars/all/all.yml](./ansible/group_vars/all/all.yml)</code>. It installs the <code><a href="https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack" target="_blank">kube-prometheus-stack</a></code> chart with custom values. Make sure to fill and modify those values at <code>[ansible/01-playbook/roles/monitoring/files/values.yaml](./ansible/01-playbook/roles/monitoring/files/values.yaml)</code>.
+<br />
+
+Tasks have its own <b>tags</b>, use these tags to update only the desired sections. For example update the values of the monitoring task, run:
+```
+ansible-playbook -i ../ansible_inventory --user=ubuntu --become --become-user=root play.yml --tags monitoring
+```
+### Access the services
+```
+kubectl get svc -n monitoring
+kubectl port-forward svc/<service-name> <local_port>:<service_port> -n monitoring
+# For example:
+# kubectl port-forward svc/prometheus-operated 9090:9090 -n monitoring
+# kubectl port-forward svc/prometheus-community-grafana  3000:80 -n monitoring
+# Access the service in browser with <localhost>:<port>
+```
+For information on <b>persistent volume</b>, <b>alertmanager</b> and <b>grafana</b> configuration, refer to the [docs](./ansible/docs/).
 ## Cleanup
 ### Delete kubernetes cluster
 ```

ansible/docs/alertmanager.md

+### Alerting
+Configuration in values is set up for Slack and e-mail notifications. For Slack you need to get the [webhook](https://docs.kubermatic.com/kubermatic/v2.25/tutorials-howtos/monitoring-logging-alerting/user-cluster/setting-up-alertmanager-with-slack-notifications/#setting-up-slack-incoming-webhooks) URL and specify it under <code>.slack_configs.api_url</code>. For email alerts, provide the receiver's e-mail address, the SMTP server address and preferably configure a service account to act as the sender, then input these details in the relevant fields under  <code>.email_configs</code>.
+If you want to use different receiver refer to the [docs](https://prometheus.io/docs/alerting/latest/configuration/#general-receiver-related-settings).<br />
+To ignore specific alerts, add the alert name to <code>alertmanager.config.route.routes</code> under <code>receiver: 'null'</code>, and include it in the <code>alertname</code> field.
\ No newline at end of file

ansible/docs/grafana.md

+### Grafana
+- In the default monitoring settings change the adminPassword. 
+- The MacOS dashboard is disabled by default. To enable it, set <code>nodeExporter.operatingSystems.darwin.enabled: True</code>. 
+- The default configuration uses default grafana login. To use only the default grafana login without external access comment out the <code>ingress</code>, <code>assertNoLeakedSecrets</code> and <code>grafana.ini</code> sections under the <code>grafana</code> configuration.
+#### Ingress
+To manage external access to Grafana, you need to switch <code>install_nginx_task: true</code> to install the [ingress controller](https://github.com/kubernetes/ingress-nginx) with helm chart. Ensure that you have your own external domain address and specify it under <code>grafana.ingress.hosts</code> in the monitoring values. Check if the ingress has been succesfully created:
+```
+kubectl get ingress -n monitoring
+```
+#### Cert-manager
+To add the HTTPS support switch <code>install_cert_manager_task: true</code>, which installs the [cert-manager](https://github.com/cert-manager/cert-manager/tree/master) helm chart and applies the <code>prod_issuer.yaml</code> manifest. Provide your domain address at <code>grafana.ingress.tls.hosts</code> and into the manifest specify your e-mail address. Check if the certificate has been succesfully created:
+```
+kubectl get certificate -n monitoring
+```
+#### Perun OAuth
+To enable OAuth authentication with Perun, first ensure that <b>Ingress</b> is set up and preferably configure HTTPS with <b>Cert-manager</b>. Also, enable OAuth authentication by setting <code>auth.generic_oauth.enabled: true</code>. To register the service, fill out this [form](https://spadmin.e-infra.cz/auth/requests/new).  For details on connecting the service, refer to the [docs](https://perunaai.atlassian.net/wiki/spaces/EINFRACZ/pages/3932161/Connecting+the+service).
+```
+Important fields of the form:
+- Choose OIDC as authentication method
+Page [1]:
+- URL of login page: https://<grafana.domain.cz>/login # input your domain address
+Page [3]:
+- Redirect URIs: https://<grafana.domain.cz>/login/generic_oauth # input your domain address
+- Flow the service will use: authorization code, token exchange
+- Token endpoint authentication method: client_secret_basic
+- Proof Key for Code Exchange (PKCE) Code Challenge Method: SHA256 code challenge
+- Scopes the service will use: openid, profile, email
+```
+Once the request is accepted, you should see the client id and secret at [My services](https://spadmin.e-infra.cz/auth/facilities/myServices) under the SAML/OIDC tab, input these into the monitoring config at <code>.auth.generic_oauth</code> section. Additionally, set the <code>.server.root_url</code> to your domain address, including the protocol.
\ No newline at end of file

ansible/docs/persistent_volume.md

+### Persistent volume and retention
+Ansible installs the <code>storageClass</code> task that is used for volume claim <code>prometheus.prometheusSpec.storageSpec.volumeClaimTemplate</code>. The values of the volume claim like storage size or retention time and size can be modified in monitoring values file under the <code>prometheus</code> section.<br />
+
+You can also increase the storage size after it has been already applied. The steps are outlined below:
+```
+kubectl get pvc -n monitoring
+kubectl edit pvc -n monitoring <pvc-name>
+```
+Change the size located at <code>.spec.resources.requests.storage</code>. When using the vi/vim editor press <code>Insert</code> and change the value. After changing the value press <code>Esc</code> and type <code>:wq</code> and confirm it. Wait for changes to take effect. <br />
+Check if the changes were succesfully applied with:
+```
+kubectl get pvc -n monitoring
+```
\ No newline at end of file