Add configurable ingress domain with automatic nip.io fallback (#50)

Author: gablyu-oci

GETTING_STARTED_HELM_DEPLOY.md

@@ -100,9 +100,15 @@ helm install lens oci-ai-incubations/lens -n lens --create-namespace \
   --set grafana.adminPassword="access password for grafana portal. User name is admin by default"\
   --set monitoring.grafanaAdminPassword="password" \
   --set backend.tenancyId="your-oci-tenancy-id" \
-  --set backend.regionName="your-oke-region-name" 
+  --set backend.regionName="your-oke-region-name"
 ```
 
+**Optional: Custom Domain Configuration**
+
+By default, the deployment uses `nip.io` for ingress (no DNS setup required). To use your own domain, add `--set ingress.domain="your-domain"` to the helm command above.
+
+For detailed instructions on custom domain setup and required DNS records, see [Custom Domain Configuration](INGRESS_AND_TLS_SETUP.md#custom-domain-configuration).
+
 ### OPTION 2: Install control plane with your existing grafana & prometheus to existing OKE cluster
 
 If you already have Prometheus Postgateway and Grafana running, login to existing OKE cluster where you would like to install this:
@@ -123,10 +129,15 @@ helm install lens oci-ai-incubations/lens -n lens --create-namespace \
   --set backend.superuser.username="username for API & control plane e.g. admin" \
   --set backend.superuser.email="your email" \
   --set backend.superuser.password="access password for API & control plane" \
-  --set grafana.adminPassword="access password for grafana portal. User name is admin by default" \
- 
+  --set grafana.adminPassword="access password for grafana portal. User name is admin by default"
 ```
 
+**Optional: Custom Domain Configuration**
+
+By default, the deployment uses `nip.io` for ingress (no DNS setup required). To use your own domain, add `--set ingress.domain="your-domain"` to the helm command above.
+
+For detailed instructions on custom domain setup and required DNS records, see [Custom Domain Configuration](INGRESS_AND_TLS_SETUP.md#custom-domain-configuration).
+
 ## Verify for successful install
 
 Once the installation is complete you should see the following pods in the "lens" namespace. If you don't please uninstall and reinstall or check the helm install events/logs. 

GETTING_STARTED_RM_DEPLOY.md

@@ -59,6 +59,7 @@ The deployment automatically installs **ingress-nginx** and **cert-manager** for
    - Configure parameters:
       - **Create IAM Policy:** Enable if you wish to create the workload identity IAM policy for the backend service account.
       - **IAM Policy Name:** Default is `corrino-lens-backend-workload-policy`
+      - **Ingress Domain:** (Optional) Custom domain for ingress. Leave empty to use `nip.io` wildcard DNS service (recommended for quick start, no DNS setup required). If you provide a custom domain, you must manually create DNS records. See [Custom Domain Configuration](INGRESS_AND_TLS_SETUP.md#custom-domain-configuration) for details.
       - **Superuser Username:** Username for the OCI GPU Scanner Portal (default: `admin`)
       - **Superuser Password:** Password for the OCI GPU Scanner Portal (default: `supersecret`) — **Recommended to change for production**
       - **Superuser Email:** Email address for the superuser account (default: `admin@oracle.com`)
@@ -75,7 +76,9 @@ Access the OKE cluster using the credentials created for the new OKE cluster.
 After connecting with OKE cluster run the below command
 ```kubectl get ingress -n lens```
 
-Copy the HOSTS details for all the applications deployed by lens. e.g. lens.129.80.43.138.nip.io 
+Copy the HOSTS details for all the applications deployed by lens. e.g. lens.129.80.43.138.nip.io
+
+**Note:** If you configured a custom domain during deployment, you need to manually create DNS records. See [Custom Domain Configuration](INGRESS_AND_TLS_SETUP.md#custom-domain-configuration) for detailed instructions.
 
 
 

INGRESS_AND_TLS_SETUP.md

@@ -97,6 +97,75 @@ kubectl get crd | grep cert-manager || echo "No cert-manager CRDs"
 
 ---
 
+## Custom Domain Configuration
+
+By default, OCI GPU Scanner uses `nip.io` for ingress, which is a wildcard DNS service that requires no manual DNS configuration. All URLs will be in the format `<service>.<LOADBALANCER_IP>.nip.io` (e.g., `lens.129.80.43.138.nip.io`).
+
+### Using nip.io (Default - Recommended for Quick Start)
+
+**No DNS configuration required!** The deployment automatically uses `nip.io`, which provides wildcard DNS resolution based on the LoadBalancer IP address.
+
+**Helm installation:** No additional parameters needed - this is the default behavior.
+
+**Resource Manager:** Leave the "Ingress Domain" field empty.
+
+### Using a Custom Domain
+
+If you prefer to use your own domain instead of `nip.io`, you can configure a custom domain during installation. However, you **must manually create DNS A records** in your DNS provider.
+
+If you prefer to use `.oci-incubations.com` as your domain, contact amar.gowda@oracle.com or gabrielle.lyu@oracle.com for adding DNS A records after deployment.
+
+#### Step 1: Configure Custom Domain During Installation
+
+**For Helm installations:**
+```bash
+helm install lens oci-ai-incubations/lens -n lens --create-namespace \
+  --set ingress.domain="your-domain" \
+  [... other parameters ...]
+```
+
+**For Resource Manager deployments:**
+Enter your domain in the "Ingress Domain" field (e.g., `oci-incubations.com`).
+
+#### Step 2: Get the LoadBalancer IP
+
+After deployment completes, retrieve the ingress LoadBalancer IP:
+
+```bash
+kubectl get svc lens-ingress-nginx-controller -n lens
+```
+
+Look for the `EXTERNAL-IP` value (e.g., `137.131.36.226`).
+
+#### Step 3: Create DNS A Records
+
+In your DNS provider, create the following DNS A records pointing to the LoadBalancer IP:
+
+| DNS Record | Points To |
+|------------|-----------|
+| `*.<LOADBALANCER_IP>.<YOUR_DOMAIN>` | `<LOADBALANCER_IP>` |
+
+
+**Example:** For LoadBalancer IP `137.131.36.226` and domain `oci-incubations.com`:
+- `*.137.131.36.226.oci-incubations.com` → `137.131.36.226`
+
+#### Step 4: Verify DNS Resolution
+
+After creating the DNS records (allow 5-15 minutes for DNS propagation):
+
+```bash
+# Test DNS resolution
+nslookup lens.137.131.36.226.oci-incubations.com
+nslookup api.137.131.36.226.oci-incubations.com
+
+# Test HTTPS access
+curl -I https://lens.137.131.36.226.oci-incubations.com
+```
+
+**Note:** TLS certificates from Let's Encrypt may take 2-5 minutes to be issued after DNS records are properly configured.
+
+---
+
 ## Post-Install Check
 
 After helm installation, verify all components are running:

oci_lens_terraform/main.tf

@@ -131,6 +131,7 @@ module "app" {
   superuser_password = var.superuser_password
   superuser_email    = var.superuser_email
   grafana_admin_password = var.grafana_admin_password
+  ingress_domain    = var.ingress_domain
 
   # wait for cluster (if new cluster was created)
   depends_on = [time_sleep.after_cluster]

oci_lens_terraform/modules/app/main.tf

@@ -65,6 +65,11 @@ resource "helm_release" "app" {
     value = var.grafana_admin_password
   }
 
+  set {
+    name = "ingress.domain"
+    value = var.ingress_domain != "" ? var.ingress_domain : "nip.io"
+  }
+
   depends_on = [
     kubernetes_namespace.ns,
   ]

oci_lens_terraform/modules/app/variables.tf

@@ -59,4 +59,10 @@ variable "grafana_admin_password" {
   description = "Password for the admin of Grafana"
   type = string
   sensitive = true
+}
+
+variable "ingress_domain" {
+  description = "Domain for ingress. Empty string defaults to nip.io."
+  type = string
+  default = ""
 }

oci_lens_terraform/schema.yaml

@@ -21,6 +21,7 @@ variableGroups:
     visible: true
     variables:
       - namespace
+      - ingress_domain
       - create_iam_policy
       - policy_name
 
@@ -62,6 +63,12 @@ variables:
     description: "Namespace for all Lens resources."
     default: "lens"
 
+  ingress_domain:
+    type: string
+    title: "Ingress Domain"
+    description: "Custom domain for ingress. Leave empty to use nip.io (wildcard DNS service)."
+    default: ""
+
   create_iam_policy:
     type: boolean
     title: "Create IAM Policy"

oci_lens_terraform/variables.tf

@@ -56,4 +56,10 @@ variable "grafana_admin_password" {
   type        = string
   sensitive   = true
   default     = "admin123"
+}
+
+variable "ingress_domain" {
+  description = "Domain for ingress. Leave empty to use nip.io (wildcard DNS service)."
+  type        = string
+  default     = ""
 }