diff --git a/docs/installing-lagoon/bulk-storage-provisioner.md b/docs/installing-lagoon/bulk-storage-provisioner.md new file mode 100644 index 0000000000..4afe2bc392 --- /dev/null +++ b/docs/installing-lagoon/bulk-storage-provisioner.md @@ -0,0 +1,64 @@ +# Bulk Storage Provisioner + + +## AWS-specific instructions +!!! Info + The EFS info here is only applicable to AWS installations, but the basic process should be similar for all NFS volumes. + +In order to create the necessary `Bulk` StorageClass, you will need to have an RWX-capable storage backend. + +In this example, we will provide documentation to configure EFS as a NFS server, and configure that for use with Lagoon + +### Requirements +1. Provision and configure an EFS, taking note of any security group requirements (https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-mount-cmd-dns-name.html) +2. The DNS name for the mount target of the EFS volume - usually `file-system-id.efs.aws-region.amazonaws.com` +3. Familiarity with the NFS CSI driver for Kubernetes - https://github.com/kubernetes-csi/csi-driver-nfs + +### Steps + +1. Add Helm repository for the NFS CSI driver + ```bash title="Add Helm repo" + helm repo add csi-driver-nfs https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts + ``` +2. Configure the `bulk` StorageClass EFS NFS mount target in a values file. Note that this step also installs a secret into the namespace to handle deleting volumes, as per [here](https://github.com/kubernetes-csi/csi-driver-nfs/issues/260) + + ```yaml title="csi-driver-nfs-storageclass.yaml" hl_lines="7" + apiVersion: storage.k8s.io/v1 + kind: StorageClass + metadata: + name: bulk + provisioner: nfs.csi.k8s.io + parameters: + server: file-system-id.efs.aws-region.amazonaws.com + share: / + csi.storage.k8s.io/provisioner-secret-name: "mount-options" + csi.storage.k8s.io/provisioner-secret-namespace: "csi-driver-nfs" + reclaimPolicy: Delete + volumeBindingMode: Immediate + mountOptions: + - nfsvers=4.1 + - rsize=1048576 + - wsize=1048576 + - hard + - timeo=600 + - retrans=2 + - noresvport + --- + apiVersion: v1 + kind: Secret + metadata: + name: mount-options + namespace: csi-driver-nfs + stringData: + mountOptions: "nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport" + ``` +3. Install the NFS CSI driver + ```bash title="Install NFS CSI Driver" + helm upgrade --install --create-namespace \ + --namespace csi-driver-nfs --wait \ + csi-driver-nfs csi-driver-nfs/csi-driver-nfs + ``` +4. Install the StorageClass and secret + ```bash title="Install bulk StorageClass and Secret" + kubectl apply -f csi-driver-nfs-storageclass.yaml + ``` diff --git a/docs/installing-lagoon/efs-provisioner.md b/docs/installing-lagoon/efs-provisioner.md deleted file mode 100644 index c64caa8f90..0000000000 --- a/docs/installing-lagoon/efs-provisioner.md +++ /dev/null @@ -1,37 +0,0 @@ -# EFS Provisioner - -!!! Info - This is only applicable to AWS installations. - -1. Add Helm repository: - - ```bash title="Add Helm repo" - helm repo add stable https://charts.helm.sh/stable - ``` - -2. Create `efs-provisioner-values.yml` in your config directory and update the values: - - ```yaml title="efs-provisioner-values.yml" - efsProvisioner: - efsFileSystemId: - awsRegion: - path: / - provisionerName: example.com/aws-efs - storageClass: - name: bulk - isDefault: false - reclaimPolicy: Delete - mountOptions: [] - global: - deployEnv: prod - - ``` - -3. Install EFS Provisioner: - - ```bash title="Install EFS Provisioner" - helm upgrade --install --create-namespace \ - --namespace efs-provisioner --wait \ - -f efs-provisioner-values.yaml \ - efs-provisioner stable/efs-provisioner - ``` diff --git a/docs/installing-lagoon/requirements.md b/docs/installing-lagoon/requirements.md index 27d451da5f..8a530245c5 100644 --- a/docs/installing-lagoon/requirements.md +++ b/docs/installing-lagoon/requirements.md @@ -53,7 +53,7 @@ Lagoon utilizes a default 'standard' `StorageClass` for most workloads, and the Lagoon also requires a `StorageClass` called 'bulk' to be available to support persistant pod replicas (across nodes). This `StorageClass` should support `ReadWriteMany` (RWX) access mode and should be configured to be dynamic provisioning and expandable where possible. See https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes for more information, and the [production drivers list](https://kubernetes-csi.github.io/docs/drivers.html) for a complete list of compatible drivers. -We have curently only included the instructions for (the now deprecated) [EFS Provisioner](./efs-provisioner.md). The production [EFS CSI driver](https://github.com/kubernetes-sigs/aws-efs-csi-driver) has issues with provisioning more than 120 PVCs. We are awaiting upstream possible fixes [here](https://github.com/kubernetes-sigs/aws-efs-csi-driver/pull/761) and [here](https://github.com/kubernetes-sigs/aws-efs-csi-driver/pull/732) - but most other providers CSI drivers should also work, as will configurations with an NFS-compatible server and provisioner. +We have curently only included the instructions a generic Bulk Storage provisioner using NFS [Bulk Storage Provisioner](./bulk-storage-provisioner.md). In AWS the production [EFS CSI driver](https://github.com/kubernetes-sigs/aws-efs-csi-driver) is limited to provisioning no more than 1000 PVCs. We are awaiting an upstream possible fix [here](https://github.com/kubernetes-sigs/aws-efs-csi-driver/pull/732) - but most other providers CSI drivers should also work, as will configurations with an NFS-compatible server and provisioner. ## How much Kubernetes experience/knowledge is required? diff --git a/mkdocs.yml b/mkdocs.yml index 66a781035e..f951cdfde7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -125,7 +125,7 @@ nav: - Kibana Examples: logging/kibana-examples.md - Installing Lagoon: - Requirements: installing-lagoon/requirements.md - - EFS Provisioner: installing-lagoon/efs-provisioner.md + - Bulk storage Provisioner: installing-lagoon/bulk-storage-provisioner.md - Install Harbor: installing-lagoon/install-harbor.md - Install Lagoon Core: installing-lagoon/lagoon-core.md - Install Lagoon Remote: installing-lagoon/install-lagoon-remote.md @@ -495,3 +495,4 @@ plugins: 'drupal/services/php-cli-drupal.md': 'applications/drupal/services/php-cli.md' 'drupal/services/solr-drupal.md': 'applications/drupal/services/solr.md' 'drupal/services/varnish-drupal.md': 'applications/drupal/services/varnish.md' + 'installing-lagoon/efs-provisioner.md': 'installing-lagoon/bulk-storage-provisioner.md'