.terraform-docs.yml

formatter: "markdown" # this is required

version: ""

header-from: main.tf
footer-from: ""

recursive:
  enabled: false
  path: modules

sections:
  hide: []
  show: []

content: |-
  # Nebuly Platform (AWS)

  Terraform module for provisioning Nebuly Platform resources on AWS.

  Available on [Terraform Registry](https://registry.terraform.io/modules/nebuly-ai/nebuly-platform/aws/latest).

  ## Quickstart

  > ⚠️  **Prerequisite**:
  > before using this Terraform module, ensure that you have your Nebuly credentials ready. 
  > These credentials are necessary to activate your installation and should be provided as input via the `nebuly_credentials` input.

  To get started with Nebuly installation on AWS, you can follow the steps below. 

  These instructions will guide you through the installation using Nebuly's default standard configuration with the Nebuly Helm Chart.

  For specific configurations or assistance, reach out to the Nebuly Slack channel or email [support@nebuly.ai](mailto:support@nebuly.ai).

  ### 1. Terraform setup

  Import Nebuly into your Terraform root module, provide the necessary variables, and apply the changes.

  For configuration examples, you can refer to the [Examples](#examples). 

  Once the Terraform changes are applied, proceed with the next steps to deploy Nebuly on the provisioned Elastic Kubernetes Service (EKS) cluster.

  <details>
  <summary>Required IAM Policies</summary>

  The following are the IAM policies required by the IAM users used to run the Terraform scripts:
  - **AmazonRDSFullAccess**
  - **AmazonS3FullAccess:**
  - **AmazonEKSClusterPolicy**
  - **AmazonEKSServicePolicy**
  - **SecretsManagerReadWrite**
  - **CloudWatchFullAccess**
  - **AmazonVPCFullAccess**

  </details>

  <details>
  <summary>Required EKS Custom Policy</summary>

  ```json
    {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "ec2:CreateLaunchTemplate",
                  "ec2:DeleteLaunchTemplate",
                  "ec2:DescribeLaunchTemplates",
                  "ec2:DescribeLaunchTemplateVersions",
                  "ec2:RunInstances",
                  "kms:TagResource",
                  "eks:*",
                  "kms:CreateKey",
                  "kms:CreateAlias",
                  "kms:DeleteAlias",
                  "iam:CreateRole",
                  "iam:DeleteRole",
                  "iam:CreatePolicy",
                  "iam:DeletePolicy",
                  "iam:AttachRolePolicy",
                  "iam:PutRolePolicy",
                  "iam:GetRolePolicy",
                  "iam:DetachRolePolicy",
                  "iam:DeleteRolePolicy"
              ],
              "Resource": [
                  "*"
              ]
          }
      ]
  }
  ```

  </details>

  ### 2. Connect to the EKS cluster

  Prerequisites: install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).

  * Fetch the command for retrieving the credentials from the module outputs:

  ```shell
  terraform output eks_cluster_get_credentials
  ```

  * Run the command you got from the previous step

  ### 3. Create image pull secret

  The auto-generated Helm values use the name defined in the k8s_image_pull_secret_name input variable for the Image Pull Secret. If you prefer a custom name, update either the Terraform variable or your Helm values accordingly.
  Create a Kubernetes [Image Pull Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for 
  authenticating with your Docker registry and pulling the Nebuly Docker images.

  ### 4. Bootstrap EKS cluster

  Retrieve the auto-generated values from the Terraform outputs and save them to a file named `values-bootstrap.yaml`:

  ```shell
  terraform output helm_values_bootstrap
  ```

  Install the bootstrap Helm chart to set up all the dependencies required for installing the Nebuly Platform Helm chart on EKS.

  Refer to the [chart documentation](https://github.com/nebuly-ai/helm-charts/tree/main/bootstrap-aws) for all the configuration details.

  ```shell
  helm install oci://ghcr.io/nebuly-ai/helm-charts/bootstrap-aws \
    --namespace nebuly-bootstrap \
    --generate-name \
    --create-namespace \
    -f values-bootstrap.yaml
  ```


  ### 5. Create Secret Provider Class
  Create a Secret Provider Class to allow EKS to fetch credentials from the provisioned Key Vault.

  * Get the Secret Provider Class YAML definition from the Terraform module outputs:
    ```shell
    terraform output secret_provider_class
    ```

  * Copy the output of the command into a file named secret-provider-class.yaml.

  * Run the following commands to install Nebuly in the Kubernetes namespace nebuly:

    ```shell
    kubectl create ns nebuly
    kubectl apply --server-side -f secret-provider-class.yaml
    ```


  ### 6. Install nebuly-platform chart

  Retrieve the auto-generated values from the Terraform outputs and save them to a file named `values.yaml`:

  ```shell
  terraform output helm_values
  ```

  Install the Nebuly Platform Helm chart. 
  Refer to the [chart documentation](https://github.com/nebuly-ai/helm-charts/tree/main/nebuly-platform) for detailed configuration options.

  ```shell
  helm install <your-release-name> oci://ghcr.io/nebuly-ai/helm-charts/nebuly-platform \
    --namespace nebuly \
    -f values.yaml \
    --timeout 30m 
  ```

  > ℹ️  During the initial installation of the chart, all required Nebuly LLMs are uploaded to your model registry. 
  > This process can take approximately 5 minutes. If the helm install command appears to be stuck, don't worry: it's simply waiting for the upload to finish.

  ### 7. Access Nebuly

  Retrieve the external Load Balancer DNS name to access the Nebuly Platform:

  ```shell
  kubectl get svc -n nebuly-bootstrap -o jsonpath='{range .items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[0].ip}{"\n"}{end}'
  ```

  You can then register a DNS CNAME record pointing to the Load Balancer DNS name to access Nebuly via the custom domain you provided 
  in the input variable `platform_domain`.


  ## Examples

  You can find examples of code that uses this Terraform module in the [examples](./examples) directory.

  {{ .Header }}


  {{ .Providers }}


  {{ .Outputs }}


  {{ .Inputs }}

  ## Resources

  {{ range .Module.Resources }}
  - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
  {{- end }}

output:
  file: ""
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: false
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: false
  read-comments: true
  required: true
  sensitive: true
  type: true