Merge pull request #5884 from influxdata/jts/dar-484-add-steps-to-install-kubit-in-an-air-gapped-environment

fix(clustered): set up clustered for air-gapped environments, add ins…

Author: jstirnaman

content/influxdb3/clustered/install/_index.md

@@ -37,14 +37,22 @@ installing InfluxDB Clustered.
 
 ## Setup, configure, and deploy InfluxDB Clustered
 
-{{< children type="ordered-list" >}}
+> [!Note]
+> #### Deploying in air-gapped environments
+>
+> To deploy InfluxDB Clustered in an air-gapped environment (without internet access),
+> use one of the following approaches:
+>
+> - **Recommended**: Directly use `kubit local apply`
+> - Helm (includes the kubit operator)
+> - Directly use the kubit operator
+> 
+> For more information, see [Choose the right deployment tool for your environment](/influxdb3/clustered/install/set-up-cluster/configure-cluster/#choose-the-right-deployment-tool-for-your-environment)
 
+{{< children type="ordered-list" >}}
 
 <!-- TODO: ADD CLUSTER ARCHITECTURE OVERVIEW -->
-
-<!--
-
--------- TODO: ALL THIS INFORMATION NEEDS TO LAND IN THE ADMIN SECTION ---------
+<!---------- TODO: ALL THIS INFORMATION NEEDS TO LAND IN THE ADMIN SECTION ---------
 
 ### Updating your InfluxDB Cluster
 

content/influxdb3/clustered/install/set-up-cluster/configure-cluster/_index.md

@@ -20,9 +20,64 @@ The AppInstance CRD is defined in a YAML file (use the `example-customer.yml`
 provided by InfluxData as a template).
 
 We recommend editing the `AppInstance` resource directly as the primary method
-for configuring and managing your InfluxDB cluster. If you are required to use
-[Helm](https://helm.sh/), there is a InfluxDB Clustered Helm chart available
+for configuring and managing your InfluxDB cluster.
+After you have edited your `AppInstance`, use the `kubit` CLI or `kubectl` [deployment tool](/influxdb3/clustered/install/set-up-cluster/configure-cluster/#choose-the-right-deployment-tool-for-your-environment), depending on your requirements.
+
+If you are required to use
+[Helm](https://helm.sh/), there is an InfluxDB Clustered Helm chart available
 that acts as a wrapper for the `AppInstance` resource and lets you use Helm to
 manage configuration changes in your InfluxDB cluster.
 
+{{% expand-wrapper %}}
+{{% expand "Choose the right deployment tool for your environment" %}}
+
+| Deployment Tool | Best For | Requirements | Considerations |
+|----------------|----------|--------------|----------------|
+| [**kubectl**](#when-to-use-kubectl) | Standard deployments | Cluster-wide permissions | Simplest option if you have required permissions |
+| [**kubit CLI**](#when-to-use-kubit-cli) | Limited permission environments or air-gapped | Local workstation access | Better for environments with permission restrictions |
+| [**Helm**](#when-to-use-helm) | Teams standardized on Helm | Helm installation (includes kubit operator) | Provides consistent deployment with other Helm-managed applications |
+
+### When to use kubectl
+
+Use the `kubectl` approach when:
+
+- You have cluster-wide permissions to install CRDs
+- You prefer the simplest deployment method
+
+> [!important]
+> 
+> #### kubectl requires cluster-wide permissions
+>
+> InfluxDB Clustered uses an `AppInstance` Kubernetes custom resource (CR) to
+> configure and deploy your InfluxDB Cluster. Installing a `CustomResourceDefinition` 
+> (CRD) requires cluster-wide permissions, so if you don't have these permissions, 
+> `kubectl` may fail.
+
+### When to use kubit CLI
+
+Use the `kubit local apply` CLI approach when:
+
+- You don't have permissions to install CRDs
+- You don't have permissions to install operators in the `kubit` namespace
+- You don't have permissions to create cluster-wide RBAC
+- You're working in an air-gapped environment
+- You want to preview generated YAML before applying
+- You don't want to run the operator in your cluster
+
+The `kubit local apply` method is specifically designed to avoid having to install the operator in air-gapped environments, making it easier to implement. This approach processes the AppInstance resource on your local machine and then applies the resulting Kubernetes resources directly to the cluster without requiring the kubit operator to be running in the cluster.
+
+### When to use Helm
+
+Use the `Helm` approach when:
+
+- Your team is standardized on Helm for Kubernetes deployments
+- You prefer consistent deployment methods across applications
+- You want simplified management of the full stack
+- You need better support for upgrades and rollbacks
+
+The InfluxDB Clustered Helm chart includes the [kubecfg kubit operator](/influxdb3/clustered/install/set-up-cluster/configure-cluster/use-helm/#kubecfg-kubit-operator).
+
+{{% /expand %}}
+{{% /expand-wrapper %}}
+
 {{< children >}}

content/influxdb3/clustered/install/set-up-cluster/configure-cluster/directly.md

@@ -128,15 +128,15 @@ In both scenarios, you need a valid _pull secret_.
 
 {{< tabs-wrapper >}}
 {{% tabs %}}
-[Public registry (non-air-gapped)](#)
+[Public registry](#)
 [Private registry (air-gapped)](#)
 {{% /tabs %}}
 
 {{% tab-content %}}
 
 <!--------------------------- BEGIN Public Registry --------------------------->
 
-#### Public registry (non-air-gapped)
+#### Public registry
 
 To pull from the InfluxData registry, you need to create a Kubernetes secret in the target namespace.
 
@@ -161,40 +161,34 @@ If you change the name of the secret, you must also change the value of the
 {{% /tab-content %}}
 {{% tab-content %}}
 
-<!--------------------------- BEGIN Private Registry -------------------------->
+<!--------------------------- BEGIN PRIVATE REGISTRY (AIR-GAPPED) -------------------------->
 
 #### Private registry (air-gapped)
 
 If your Kubernetes cluster can't use a public network to download container images
-from the InfluxData container registry, do the following:
+from the InfluxData container registry, follow these steps to copy images and
+configure the AppInstance for a private registry:
 
-1.  Copy the images from the InfluxData registry to your own private registry.
-2.  Configure your `AppInstance` resource with a reference to your private
-    registry name.
-3.  Provide credentials to your private registry.
+1. [Copy the images to your private registry](#copy-the-images-to-your-private-registry)
+2. [Configure your AppInstance](#configure-your-appinstance)
 
-##### Copy the images
+##### Copy the images to your private registry
 
-We recommend using [crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane)
-to copy images into your private registry.
+Use `crane` to copy images from the InfluxData registry to your own private registry.
 
-1.  [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation)
-    for your system.
-2.  Use the following command to create a container registry secret file and
-    retrieve the necessary secrets:
+1. [Install crane](https://github.com/google/go-containerregistry/tree/main/cmd/crane#installation)
+   for your system.
+2. Create a container registry secret file and verify access:
 
 {{% code-placeholders "PACKAGE_VERSION" %}}
 
-<!-- pytest.mark.skip -->
-
 ```bash
-mkdir /tmp/influxdbsecret
+mkdir -p /tmp/influxdbsecret
 cp influxdb-docker-config.json /tmp/influxdbsecret/config.json
 DOCKER_CONFIG=/tmp/influxdbsecret \
   crane manifest \
   us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:PACKAGE_VERSION
 ```
-
 {{% /code-placeholders %}}
 
 ---
@@ -244,8 +238,8 @@ manifest and the output is similar to the following error:
 Error: fetching manifest us-docker.pkg.dev/influxdb2-artifacts/clustered/influxdb:<package-version>: GET https://us-docker.pkg.dev/v2/token?scope=repository%3Ainfluxdb2-artifacts%2Fclustered%2Finfluxdb%3Apull&service=: DENIED: Permission "artifactregistry.repositories.downloadArtifacts" denied on resource "projects/influxdb2-artifacts/locations/us/repositories/clustered" (or it may not exist)
 ```
 
-The list of images that you need to copy is included in the package metadata.
-You can obtain it with any standard OCI image inspection tool--for example:
+3. Extract the list of InfluxDB images from the package metadata:
+You can use any standard OCI image inspection tool--for example:
 
 {{% code-placeholders "PACKAGE_VERSION" %}}
 
@@ -269,7 +263,7 @@ us-docker.pkg.dev/influxdb2-artifacts/iox/iox@sha256:b59d80add235f29b806badf7410
 ...
 ```
 
-Use `crane` to copy the images to your private registry:
+4. Use `crane` to copy the images to your private registry:
 
 {{% code-placeholders "REGISTRY_HOSTNAME" %}}
 
@@ -289,49 +283,50 @@ with the hostname of your private registry--for example:
 myregistry.mydomain.io
 ```
 
-
 ##### Configure your AppInstance
 
-Set the `spec.package.spec.images.registryOverride` field in your
-`myinfluxdb.yml` to the location of your private registry--for example:
+Configure your `AppInstance` resource with a reference to your private registry name.
 
-{{% code-placeholders "REGISTRY_HOSTNAME" %}}
+In your `myinfluxdb.yml`:
 
-```yml
+1. Set `spec.package.spec.images.registryOverride` to the location of your private registry.
+2. If your private container registry requires pull secrets to access images, set `spec.imagePullSecrets.name` to the pull secret name.
+
+{{% expand-wrapper %}}
+{{% expand "View `myinfluxdb.yml` AppInstance configuration" %}}
+{{% code-placeholders "REGISTRY_HOSTNAME | PULL_SECRET_NAME" %}}
+```yaml
 apiVersion: kubecfg.dev/v1alpha1
 kind: AppInstance
-# ...
+metadata:
+  name: influxdb
+  namespace: influxdb
 spec:
   package:
     spec:
       images:
         registryOverride: REGISTRY_HOSTNAME
-```
-
-{{% /code-placeholders %}}
-
-
-##### Provide credentials to your private registry
-
-If your private container registry requires pull secrets to access images, you
-can create the required kubernetes secrets, and then configure them in your
-AppInstance resource--for example:
-
-{{% code-placeholders "PULL_SECRET_NAME" %}}
-
-```yml
-apiVersion: kubecfg.dev/v1alpha1
-kind: AppInstance
-# ...
-spec:
+  # Configure connection to PostgreSQL database
+  values:
+    global:
+      catalog:
+        dsn: "postgres://username:password@postgres-host:5432/influxdb?sslmode=require"
+    # Configure S3-compatible object storage
+    objectStorage:
+      bucket: "influxdb-bucket"
+      endpoint: "https://s3-endpoint"
+      accessKeyId: "ACCESS_KEY"
+      secretAccessKey: "SECRET_KEY"
+      region: "region"
+  # Configure image pull secrets if needed
   imagePullSecrets:
     - name: PULL_SECRET_NAME
 ```
-
 {{% /code-placeholders %}}
+{{% /expand %}}
+{{% /expand-wrapper %}}
 
-
-<!---------------------------- END Private Registry --------------------------->
+<!---------------------------- END Private Registry (AIR-GAPPED) --------------------------->
 
 {{% /tab-content %}}
 {{< /tabs-wrapper >}}