# Deployment

To enable the web based Management Console, make sure both the dashboard and gateway components are enabled in your operator configuration. This ensures that the Console is deployed properly within your Kubernetes cluster.

{% hint style="warning" %}
The Management Console is currently only supported for Kubernetes deployments. Bare metal deployments are not supported.
{% endhint %}

## Example Configuration

Below is an example configuration for the Management Console to add to the existing Alluxio cluster configuration yaml file:

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  gateway:
    enabled: true
    image: <PRIVATE_REGISTRY>/alluxio-gateway
    imageTag: AI-3.6-12.0.2
  dashboard:
    enabled: true
    image: <PRIVATE_REGISTRY>/alluxio-dashboard
    imageTag: AI-3.6-12.0.2
```

## Accessing the Management Console

There are a few ways to access the console.

### Accessing via Node Hostname

The Management Console will expose its service on port 80 on its host. Use kubectl to get the hostname:

```shell
kubectl -n alx-ns get pod $(kubectl -n alx-ns get pod -l app.kubernetes.io/component=dashboard --no-headers -o custom-columns=:metadata.name) -o jsonpath='{.spec.nodeName}'
```

Assume the hostname is `foo.kubernetes.org`, then you can access the Management Console on:

```
http://foo.kubernetes.org:80/
```

### Accessing via Load Balancer

To expose the Management Console externally, you can configure a Kubernetes Service of type `LoadBalancer`. This allows traffic from outside the cluster to reach the dashboard component.

Below is an example Service definition for exposing the dashboard via a Load Balancer:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: load-balancer
  namespace: alx-ns
spec:
  type: LoadBalancer
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  selector:
    app.kubernetes.io/instance: alluxio-dashboard
    app.kubernetes.io/name: dashboard
```

Save the above as `load-balancer.yaml` and create it via

```shell
kubectl create -f load-balancer.yaml
```

Once the service is created, Kubernetes will provision an external IP or DNS name, depending on your cloud provider. You can check the status using:

```bash
kubectl -n alx-ns get service load-balancer
```

Example output:

```bash
load-balancer   LoadBalancer   171.33.111.33  some-random-string.region.elb.amazonaws.com   80:30977/TCP   8m50s
```

You can now access the Management Console in your browser using the external IP or DNS name.

## Logging Into The Console

With the default `authType` of `simple`, the login page will only request for a username. As it is meant for testing use, no validation is performed and any username will be accepted.

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-2649d11bfafba8cc7d7e979e5726a0be4458a63a%2Fweb-ui-simple-login-page.png?alt=media" alt=""><figcaption></figcaption></figure>

For production use, the authentication type should be modified to [authenticate with okta](#okta-auth-type).

## Advanced configuration

### Enable Audit Logging

Audit logging tracks user activities and system events in the Management Console for security and compliance purposes. This feature is enabled by default and requires no additional configuration.

**Accessing Audit Logs:** You can view the log files at `/opt/alluxio/dashboard/audit-logs/dashboard-audit.log` inside the web console pod.

**Configuration Example:**

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  dashboard:
    enabled: true
    image: <PRIVATE_REGISTRY>/alluxio-dashboard
    imageTag: AI-3.6-12.0.2
    auditLog:
      enabled: true  # Set to false to disable audit logging
```

### Configuring TLS Connection Between Gateway and Console

When TLS (Transport Layer Security) is enabled in your Gateway, you need to configure the Management Console to establish secure TLS connections. This involves providing a CA (Certificate Authority) certificate to the Web Console, which it will use to verify the Gateway's TLS certificate.

1. **Prepare Certificate Files**
   * Obtain a valid CA certificate file (typically named `ca.crt`)
   * Prepare the Gateway certificate (`server.crt`) and private key (`server.key`) files
   * Ensure the Gateway certificate is properly signed by the CA
2. **Create a Kubernetes Secret**

   ```bash
   # Create a secret with the CA certificate, Gateway certificate, and key
   kubectl create secret generic gateway-k8s-secret-name \
     --from-file=ca.crt=/path/to/ca.crt \
     --from-file=server.key=/path/to/server.key \
     --from-file=server.crt=/path/to/server.crt \
     --namespace=alx-ns
   ```
3. **Configure Your Alluxio Cluster**

   ```yaml
   apiVersion: k8s-operator.alluxio.com/v1
   kind: AlluxioCluster
   spec:
     gateway:
       enabled: true
       image: <PRIVATE_REGISTRY>/alluxio-gateway
       imageTag: AI-3.6-12.0.2
       tls:
         enabled: true
         secretName: gateway-k8s-secret-name 
         certFile: server.crt 
         certKeyFile: server.key 
     dashboard:
       enabled: true
       image: <PRIVATE_REGISTRY>/alluxio-dashboard
       imageTag: AI-3.6-12.0.2
       gateway:
         secretName: gateway-k8s-secret-name  
         caFile: ca.crt                  
   ```

**Important Notes:**

* The `secretName` in your configuration must exactly match the name of the created Kubernetes secret
* All filenames (`caFile`, `certFile`, `certKeyFile`) must match the filenames used in the secret
* Verify that your CA certificate and Gateway certificate are valid and not expired
* The Management Console uses the CA certificate to verify the Gateway's TLS certificate during connection
* **Critical:** The CA certificate must belong to the same certificate chain as the Gateway's certificate; using an unrelated CA will cause TLS verification failures

### Okta Auth Type

The Okta authentication provides secure enterprise-level access control for your Management Console. Follow these steps to set up and use Okta authentication:

**1. Application Configuration in Okta**

1. Log in to your Okta Admin Dashboard
2. Navigate to **Applications** > **Applications**
3. Click **Create App Integration**
4. Select the **Single-Page Application (SPA)** type
   * This application type utilizes the [Authorization Code Flow with PKCE](https://developer.okta.com/docs/guides/implement-grant-type/authcodepkce/main/#about-the-authorization-code-grant-with-pkce) for secure client-side token acquisition

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-d605f6815db8eb05e109104598556f106f9e88cd%2Fweb-ui-okta-application-type.png?alt=media" alt=""><figcaption></figcaption></figure>

5. Complete the basic configuration with your application name and some options

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-7e8e53749fb65890e846bb496bca4cc2600aac8a%2Fweb-ui-okta-general-settings.png?alt=media" alt=""><figcaption></figcaption></figure>

6. In the **Login** section of your application settings, configure:
   * **Sign-in redirect URIs**: `http://your-domain:your-port/login/callback`
   * **Sign-out redirect URIs**: `http://your-domain:your-port/user/login`
   * Replace `your-domain` and `your-port` with your actual domain and port values
   * These settings ensure proper redirection after Okta authentication completes

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-bcc02f88872ca8eb779be8abc85a51b0de3abc6e%2Fweb-ui-okta-redirect-uri.png?alt=media" alt=""><figcaption></figcaption></figure>

7. Save your application configuration

**2. User Group Assignment and Authorization**

To control access to the Management Console:

1. In your Okta Admin Dashboard, navigate to **Directory** > **Groups**

   <figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-121376b311ce8970e3fb6023f7ed36d1283084c3%2Fweb-ui-okta-create-groups.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Create user groups if they don't already exist (e.g., "Admins")
3. Assign appropriate users to these groups
4. Return to your application settings
5. Under the **Assignments** tab, assign the user groups that should have access to the Management Console

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-a8b570e21cbca6743d3c2e13dd749897fe754633%2Fweb-ui-okta-assign-to-group.png?alt=media" alt=""><figcaption></figcaption></figure>

**3. Authorization Server Configuration**

The Management Console requires specific OAuth scopes for proper operation:

1. In your Okta Admin Dashboard, navigate to **Security** > **API**
2. Select your authorization server (or create one if needed)
3. Go to the **Scopes** tab
4. Click **Add Scope**

   <figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-15627badf73d619451527a16f7f3e6f35d97174f%2Fweb-ui-okta-create-scope.png?alt=media" alt=""><figcaption></figcaption></figure>
5. Create a scope named `alluxio` with an appropriate description
6. The Management Console requires both the `openid` scope (default in Okta) and this custom `alluxio` scope
7. If authorization is enabled in your deployment, associate your specified claims with this scope. Here in the screenshot down below, the `roleFieldName` in authorization config is set to `userType` and `groupFieldName` is set to `department`. Please visit [User Roles & Access Control](https://documentation.alluxio.io/ee-ai-en/ai-3.6/start/overview/user-roles-access-control) for more information.

   <figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-d8a38964c2c220ae38b6be23cb40d55f4d88a66b%2Fweb-ui-okta-assoicate-claim-scope.png?alt=media" alt=""><figcaption></figcaption></figure>

**4. Obtaining Configuration Values**

After completing the setup, gather these values for your Management Console configuration:

1. **Okta Issuer URL**:
   * Navigate to **Security** > **API** in your Okta Admin Dashboard
   * Select your authorization server
   * Copy the Issuer URL (format: `https://your-okta-domain/oauth2/default`)
2. **Client ID**:
   * Go to your application's settings
   * Copy the Client ID from the **Client Credentials** section
3. Update your Alluxio configuration with these values:

   ```yaml
   web:
     authType: okta
     oktaIssuer: https://your-okta-domain/oauth2/default
     oktaClientID: your-client-id-value
   ```

**5. Login Process**

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-2378e58b64e6297b12233a072d512f8b1fd78f87%2Fweb-ui-okta-login-page.png?alt=media" alt=""><figcaption><p>Management Console login page with Okta option</p></figcaption></figure>

<figure><img src="https://3320860615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCpYVFyqPpAS1OeireVV3%2Fuploads%2Fgit-blob-c8f09b77b7521da50e07f05c53162f078118459e%2Fweb-ui-okta-login-page2.png?alt=media" alt=""><figcaption><p>Okta authentication portal</p></figcaption></figure>

When using Okta authentication:

1. Navigate to your Management Console URL
2. The login page will display a "Login with Okta" button
3. Click this button to be redirected to your organization's Okta authentication portal
4. Enter your Okta credentials and complete any multi-factor authentication if configured
5. Upon successful authentication, you will be redirected back to the Management Console's dashboard
6. Your session will remain active based on your Okta token configuration

**6. Troubleshooting Okta Integration**

If you encounter issues with Okta authentication:

* Verify that redirect URIs are correctly configured in both Okta and your application
* Check that users are assigned to the appropriate groups with access to the application
* Ensure the `alluxio` scope is properly created and associated with your authorization server
* Confirm that the Issuer URL and Client ID in your configuration match the values in Okta

### Configuring Authorization

The Management Console supports access control to restrict user permissions based on roles and responsibilities. Authorization can be configured to control which users can access specific features and perform certain operations within the system.

For detailed instructions on setting up and managing authorization, please refer to the [User Roles & Access Control](https://documentation.alluxio.io/ee-ai-en/ai-3.6/start/overview/user-roles-access-control) documentation.