Sync docs from Discourse (#515)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
canonical · Oct 15, 2024 · 7ec80c6 · 7ec80c6
1 parent a1fcf70
commit 7ec80c6
Show file tree

Hide file tree

Showing 26 changed files with 1,339 additions and 495 deletions.
diff --git a/docs/explanation/e-users.md b/docs/explanation/e-users.md
@@ -127,4 +127,11 @@ mysql> select Host,User,account_locked from mysql.user where User like 'mysql_ro
 
 When an application charm requests a new user through the relation/integration it can specify that the user should have the `admin` role in the `extra-user-roles` field. The `admin` role enables the new user to read and write to all databases (for the `mysql` system database it can only read data) and also to create and delete non-system databases.
 
-**Note**: `extra-user-roles` is supported by modern interface `mysql_client` only and missing for legacy `mysql` interface. Read more about the supported charm interfaces [here](/t/10249).
+**Note**: `extra-user-roles` is supported by modern interface `mysql_client` only and missing for legacy `mysql` interface. Read more about the supported charm interfaces [here](/t/10249).
+
+
+<a name="admin-port"></a>
+### Admin Port User Access
+
+The charm mainly uses the `serverconfig` user for internal operations. For connections with this user, a special admin port is used (port `33062`), which enables the charm to operate MySQL even when users connections are saturated.
+For further information on the administrative connection, refer to [MySQL docs](https://dev.mysql.com/doc/refman/8.0/en/administrative-connection-interface.html) on the topic.
diff --git a/docs/how-to/h-deploy-airgapped.md b/docs/how-to/h-deploy-airgapped.md
@@ -0,0 +1,111 @@
+# Deploy in an offline or air-gapped environment
+
+An air-gapped environment refers to a system that does not have access to the public internet.
+This guide goes through the special configuration steps for installing Charmed PostgreSQL k8s in an air-gapped environment.
+
+## Requirements
+
+Canonical does not prescribe how you should set up your specific air-gapped environment. However, it is assumed that it meets the following conditions:
+
+* A K8s cluster is running.
+* DNS is configured to the local nameservers.
+* [Juju is configured](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#configure-juju) to use local air-gapped services.
+* The [`store-admin`](https://snapcraft.io/store-admin) tool is installed and configured.
+* [Air-gapped CharmHub](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/) is installed and running.
+* Local APT and LXD Images caches are reachable.
+* An air-gapped container registry (such as [Artifactory](https://jfrog.com/artifactory/)) is reachable from the K8s cluster over HTTPS
+  *  **Note**: Secure (HTTPS) OCI access is important, otherwise Juju won’t work!
+
+## Air-gapped concept summary
+
+1. [Export](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-packages)
+2. [Transfer](https://en.wikipedia.org/wiki/Air_gap_(networking))
+3. [Import](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages)
+4. [Deploy](/t/9298) 
+
+## Air-gapped day-to-day example
+
+**1.** Exporting K8s Charms and OCI Resources are currently independent processes.
+> Sseveral improvements are planned:  [#1](https://warthogs.atlassian.net/browse/PF-5369), [#2](https://warthogs.atlassian.net/browse/PF-5185)
+
+**1.1.** Charm. The necessary charm(s) can be exported as bundle OR independently (charm-by-charm). The special store-admin tool is designed to simplify the process. At the moment exporting of Charms and OCI resources are separated, but in the future the `store-admin export` [could](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charms) export all necessary OCI resource(s)) from official CharmHub.
+
+At the moment, the store-admin exports (and includes into the blob) all the OCI resources metadata only:
+```shell
+store-admin export bundle mysql-k8s-bundle --channel=8.0/edge --series=jammy --arch=amd64
+```
+
+[details="Example output"]
+
+```shell
+> store-admin export bundle mysql-k8s-bundle --channel=8.0/edge --series=jammy --arch=amd64
+Downloading mysql-k8s-bundle revision 45 (8.0/edge)
+  [####################################]  100%
+Downloading data-integrator revision 71 (edge)
+  [####################################]  100%          
+Downloading grafana-agent-k8s revision 93 (edge)
+  [####################################]  100%          
+Downloading resources for grafana-agent-k8s
+Downloading oci-image resource agent-image revision 45
+  [####################################]  100%
+Falling back to OCI image subpath from online Charmhub for 'agent-image' in charm 'grafana-agent-k8s'.
+Downloading mysql-k8s revision 201 (8.0/edge)
+  [####################################]  100%          
+Downloading resources for mysql-k8s
+Downloading oci-image resource mysql-image revision 113
+  [####################################]  100%
+Falling back to OCI image subpath from online Charmhub for 'mysql-image' in charm 'mysql-k8s'.
+Downloading mysql-router-k8s revision 164 (8.0/edge)
+  [####################################]  100%          
+Downloading resources for mysql-router-k8s
+Downloading oci-image resource mysql-router-image revision 57
+  [####################################]  100%
+Falling back to OCI image subpath from online Charmhub for 'mysql-router-image' in charm 'mysql-router-k8s'.
+Downloading mysql-test-app revision 63 (edge)
+  [####################################]  100%          
+Downloading s3-integrator revision 59 (edge)
+  [####################################]  100%          
+Downloading self-signed-certificates revision 200 (edge)
+  [####################################]  100%          
+Downloading sysbench revision 78 (edge)
+  [####################################]  100%          
+Successfully exported charm bundle mysql-k8s-bundle: /home/ubuntu/snap/store-admin/common/export/mysql-k8s-bundle-20241006T231254.tar.gz
+
+```
+
+[/details]
+
+**1.2.** OCI: for the manual OCI export, please follow [the official CharmHub guide](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-oci-images).
+
+**2.** Transfer the binary blobs using the way of your choice into Air-gapped environment.
+
+```shell
+cp /home/ubuntu/snap/store-admin/common/export/mysql-k8s-bundle-20241006T231254.tar.gz /media/usb/
+...
+cp /media/usb/mysql-k8s-bundle-20241006T231254.tar.gz /var/snap/snap-store-proxy/common/charms-to-push/
+```
+> **Note**: always check [checksum](https://en.wikipedia.org/wiki/Checksum) for the transferred blobs!
+
+**3.** Upload the charm blobs into local Air-gapped CharmHub:
+```shell
+sudo snap-store-proxy push-charm-bundle /var/snap/snap-store-proxy/common/charms-to-push/mysql-k8s-bundle-20241006T231254.tar.gz
+```
+> **Note**: when [re-importing](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`.
+
+**4.** Upload the charm OCI into local Air-gapped OCI registry.
+
+For the manual OCI import, please follow [the official CharmHub guide](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages).
+
+**5.** [Deploy and enjoy Juju charms the usual way](/t/9298):
+```shell
+juju deploy mysql-k8s --trust
+```
+> **Note**: all the Air-gapp-deployed charms revisions and OCI resources tags/revisions must match the official CharmHub revisions/tags (users can rely in [the official release notes](/t/11878)).
+
+## Additional links:
+
+* https://docs.ubuntu.com/snap-store-proxy/en/airgap
+* https://documentation.ubuntu.com/snap-store-proxy/
+* https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/
+* https://ubuntu.com/kubernetes/docs/install-offline
+* https://charmed-kubeflow.io/docs/install-in-airgapped-environment
diff --git a/docs/how-to/h-deploy-aks.md b/docs/how-to/h-deploy-aks.md
@@ -3,20 +3,21 @@
 [Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/aks/) (AKS) allows you to quickly deploy a production ready Kubernetes cluster in Azure. To access the AKS Web interface, go to [https://portal.azure.com/](https://portal.azure.com/).
 
 ## Summary
-* [Install AKS and Juju tooling](#heading--install-aks-juju)
-* [Create a new AKS cluster](#heading--create-aks-cluster)
-* [Bootstrap Juju on AKS](#heading--boostrap-juju)
-* [Deploy charms](#heading--deploy-charms)
-* [Display deployment information](#heading--display-information)
-* [Clean up](#heading--clean-up)
+* [Install AKS and Juju tooling](#install-aks-and-juju-tooling)
+  * [Authenticate](#authenticate)
+* [Create a new AKS cluster](#create-a-new-aks-cluster)
+* [Bootstrap Juju on AKS](#bootstrap-juju-on-aks)
+* [Deploy charms](#deploy-charms)
+* [Display deployment information](#display-deployment-information)
+* [Clean up](#clean-up)
 
 ---
 
-<a href="#heading--install-aks-juju"><h2 id="heading--install-aks-juju"> Install AKS and Juju tooling</h2></a>
+## Install AKS and Juju tooling
 
 Install Juju and Azure CLI tool:
 ```shell
-sudo snap install juju --classic
+sudo snap install juju
 sudo apt install --yes azure-cli
 ```
 Follow the installation guides for:
@@ -46,7 +47,7 @@ Login to your Azure account:
 az login
 ```
 
-<a href="#heading--create-aks-cluster"><h2 id="heading--create-aks-cluster"> Create a new AKS cluster</h2></a>
+## Create a new AKS cluster
 
 Export the deployment name for further use:
 ```shell
@@ -95,7 +96,7 @@ Sample output:
 Merged "aks" as current context in ~/.kube/config
 ```
 
-<a href="#heading--boostrap-juju"><h2 id="heading--boostrap-juju"> Bootstrap Juju on AKS</h2></a>
+## Bootstrap Juju on AKS
 
 Bootstrap Juju controller:
 ```shell
@@ -127,7 +128,7 @@ juju add-model welcome aks
 juju model-config logging-config='<root>=INFO;unit=DEBUG'
 ```
 
-<a href="#heading--deploy-charms"><h2 id="heading--deploy-charms">Deploy charms</h2></a>
+## Deploy charms
 
 The following command deploys MySQL K8s:
 
@@ -157,7 +158,7 @@ mysql-k8s/1   active    idle   10.244.0.15
 mysql-k8s/2   active    idle   10.244.0.16 
 ```
 
-<a href="#heading--display-information"><h2 id="heading--display-information"> Display deployment information</h2></a>
+## Display deployment information
 
 Display information about the current deployments with the following commands:
 ```shell
@@ -178,7 +179,7 @@ NAME                                STATUS   ROLES   AGE   VERSION
 aks-nodepool1-55146003-vmss000000   Ready    agent   11m   v1.28.9
 ```
 
-<a href="#heading--clean-up"><h2 id="heading--clean-up"> Clean up</h2></a>
+## Clean up
 
 [note type="caution"]
 Always clean AKS resources that are no longer necessary -  they could be costly!