Oke tfvars and instance principal (#89)

* Updated private networking docs to include kubernetes tfvars example, and removed deployment button.

* Include instance principal in OKE setup and remove it from console.

* Added instance_principal to examples.

* Don't use instance principal by default.

* Updated instance principal description.

Author: dkennetzoracle

cluster_creation_terraform/locals.tf

@@ -0,0 +1,11 @@
+# Copyright (c) 2020-2024 Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
+#
+
+locals {
+  # Authentication configuration
+  auth_config = {
+    use_instance_principal = var.use_instance_principal
+    auth_method           = var.use_instance_principal ? "InstancePrincipal" : "UserCredentials"
+  }
+} 

cluster_creation_terraform/outputs.tf

@@ -75,3 +75,25 @@ output "endpoint_subnet_id" {
   value = local.endpoint_subnet_id
 }
 
+# Authentication verification outputs
+output "authentication_method" {
+  value = var.use_instance_principal ? "InstancePrincipal" : "UserCredentials"
+  description = "The authentication method being used for OCI provider"
+}
+
+output "use_instance_principal" {
+  value = var.use_instance_principal
+  description = "Whether Instance Principal authentication is enabled"
+}
+
+output "auth_config_summary" {
+  value = {
+    use_instance_principal = var.use_instance_principal
+    auth_method           = var.use_instance_principal ? "InstancePrincipal" : "UserCredentials"
+    user_ocid_set         = var.use_instance_principal ? false : (var.user_ocid != "" && var.user_ocid != null)
+    fingerprint_set       = var.use_instance_principal ? false : (var.fingerprint != "" && var.fingerprint != null)
+    private_key_path_set  = var.use_instance_principal ? false : (var.private_key_path != "" && var.private_key_path != null)
+  }
+  description = "Summary of authentication configuration"
+}
+

cluster_creation_terraform/providers.tf

@@ -5,22 +5,33 @@
 provider "oci" {
   tenancy_ocid = var.tenancy_ocid
   region       = var.region
+  auth         = var.use_instance_principal ? "InstancePrincipal" : null
+
+  user_ocid        = var.use_instance_principal ? null : var.user_ocid
+  fingerprint      = var.use_instance_principal ? null : var.fingerprint
+  private_key_path = var.use_instance_principal ? null : var.private_key_path
 }
 
 provider "oci" {
   alias        = "home_region"
   tenancy_ocid = var.tenancy_ocid
   region       = lookup(data.oci_identity_regions.home_region.regions[0], "name")
+  auth         = var.use_instance_principal ? "InstancePrincipal" : null
 
-  user_ocid = var.user_ocid
+  user_ocid        = var.use_instance_principal ? null : var.user_ocid
+  fingerprint      = var.use_instance_principal ? null : var.fingerprint
+  private_key_path = var.use_instance_principal ? null : var.private_key_path
 }
 
 provider "oci" {
   alias        = "current_region"
   tenancy_ocid = var.tenancy_ocid
   region       = var.region
+  auth         = var.use_instance_principal ? "InstancePrincipal" : null
 
-  user_ocid = var.user_ocid
+  user_ocid        = var.use_instance_principal ? null : var.user_ocid
+  fingerprint      = var.use_instance_principal ? null : var.fingerprint
+  private_key_path = var.use_instance_principal ? null : var.private_key_path
 }
 
 # New configuration to avoid Terraform Kubernetes provider interpolation. https://registry.terraform.io/providers/hashicorp/kubernetes/2.2.0/docs#stacking-with-managed-kubernetes-cluster-resources
@@ -55,4 +66,4 @@ locals {
   cluster_ca_certificate = base64decode(yamldecode(data.oci_containerengine_cluster_kube_config.oke.content)["clusters"][0]["cluster"]["certificate-authority-data"])
   cluster_id             = yamldecode(data.oci_containerengine_cluster_kube_config.oke.content)["users"][0]["user"]["exec"]["args"][4]
   cluster_region         = yamldecode(data.oci_containerengine_cluster_kube_config.oke.content)["users"][0]["user"]["exec"]["args"][6]
-}
+}

cluster_creation_terraform/schema.yaml

@@ -28,6 +28,13 @@ variableGroups:
   - title: "Advanced Configuration?"
     variables: 
     - show_advanced
+
+  - title: "Authentication Method"
+    variables:
+    - use_instance_principal
+    visible:
+      and:
+        - show_advanced
 
   - title: "Network Configuration"
     variables:
@@ -63,6 +70,16 @@ variables:
     description: "Shows advanced options, allowing enable customer-managed encryption keys, select your ssh key, select/unselect cluster utilities, do not create policies, and other advanced options"
     visible: true
 
+  use_instance_principal:
+    description: "Terraform provider will use Instance Principal authentication instead of user credentials. Requires the compute instance to have appropriate IAM policies."
+    visible: false
+
+  fingerprint:
+    visible: false
+
+  private_key_path:
+    visible: false
+
   network_configuration_mode:
     type: enum
     enum:

cluster_creation_terraform/variables.tf

@@ -2,6 +2,25 @@
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 # 
 
+# Authentication Configuration
+variable "use_instance_principal" {
+  type        = bool
+  default     = false
+  description = "Whether to use Instance Principal for authentication. If false, user credentials will be used."
+}
+
+variable "fingerprint" {
+  type        = string
+  default     = ""
+  description = "API Key Fingerprint for user authentication. Required when use_instance_principal is false."
+}
+
+variable "private_key_path" {
+  type        = string
+  default     = ""
+  description = "Path to the private key file for user authentication. Required when use_instance_principal is false."
+}
+
 # Networking Configuration Mode
 variable "network_configuration_mode" {
   default     = "create_new"

docs/advanced/deploying_blueprints_to_private_networks/README.md

@@ -8,9 +8,24 @@ We do not create new completely locked down private subnets, but we do support t
 
 Deploying into a private subnet may likely mean the subsequent Blueprints deployment cannot be installed with the "Stack", as the stack communicates with the cluster over a public endpoint from the internet. If it is acceptable for you to have a public API endpoint but only private worker nodes, **return to the original deployment in [getting started](../../../GETTING_STARTED_README.md)**, otherwise continue.
 
-[![Deploy to Oracle Cloud](https://oci-resourcemanager-plugin.plugins.oci.oraclecloud.com/latest/deploy-to-oracle-cloud.svg)](https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-quickstart/oci-ai-blueprints/releases/download/v1.0.3/v1.0.3_cluster.zip)
+## Terraform Setup
 
-1. Click **Deploy to Oracle Cloud** above.
+It may be preferable for some users to deploy with terraform in the scenario where you bring your own network. If your networking setup does not allow for installation via the stack deployment in the OCI console, it is still possible to deploy with terraform locally using the following steps:
+
+1. Setup a bastion or get on a workstation with the ability to communicate with your cluster's API Endpoint. An example document is given above.
+2. Install the Terraform CLI from [here](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) from the bastioned host.
+3. Install the OCI CLI from [here](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) and configure authentication in your `~/.oci/config` according to [this](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliconfigure.htm).
+4. Clone our GitHub repository locally, and change directory into `oci-ai-blueprints/oci_ai_blueprints_terraform`
+5. Initialize the terraform with `terraform init`.
+6. Create a tfvars file in that directory called `terraform.tfvars`. The minimum variables needed are in [example_cluster_tfvars.md](./example_cluster_tfvars.md) and [example_blueprints_tfvars.md](./example_blueprints_tfvars.md) for each respective stack.
+7. Run a `terraform plan` to ensure nothing is missing.
+8. Run a `terraform apply` to install the Blueprints platform on your OKE cluster.
+
+**Note**: When deploying with terraform, it is important that you specify the correct stack version in the tfvars file. If you use an older version of the stack, this will be used for the blueprints version running in the control plane. If a mistake happens, it is very easy to modify the tfvars file to the correct stack version and reapply your changes, which would force an updated container pull.
+
+## Console based deployment for OKE
+
+1. Click on the deployment button in [this section](../../../GETTING_STARTED_README.md#step-2-deploy-the-vcn-and-oke-cluster), which will take you to the OKE deployment stack.
 2. In **Create Stack**:
    - Give your stack a **name** (e.g., _oke-stack_).
    - Select the **compartment** where you want OCI AI Blueprints deployed.
@@ -24,19 +39,8 @@ For documentation on access and networking configurations for locked down enviro
   - [Kubernetes API Endpoint Subnet Configuration](https://docs.oracle.com/en-us/iaas/Content/ContEng/Concepts/contengnetworkconfig.htm#subnetconfig__section_kcm_v2b_s4b)
   - [Setting Up a Bastion for Cluster Access](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengsettingupbastion.htm#contengsettingupbastion)
 
----
-
-## Deploying Blueprints with Terraform
-
-If your networking setup does not allow for installation via the stack deployment in the OCI console, it is still possible to deploy with terraform locally using the following steps:
+## Console based deployment for Blueprints
 
-1. Setup a bastion or get on a workstation with the ability to communicate with your cluster's API Endpoint. An example document is given above.
-2. Install the Terraform CLI from [here](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) from the bastioned host.
-3. Install the OCI CLI from [here](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) and configure authentication in your `~/.oci/config` according to [this](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliconfigure.htm).
-4. Clone our GitHub repository locally, and change directory into `oci-ai-blueprints/oci_ai_blueprints_terraform`
-5. Initialize the terraform with `terraform init`.
-6. Create a tfvars file in that directory called `terraform.tfvars`. The minimum variables needed are in [example_tfvars.md](./example_tfvars.md).
-7. Run a `terraform plan` to ensure nothing is missing.
-8. Run a `terraform apply` to install the Blueprints platform on your OKE cluster.
+This document describes deploying blueprints into private networks. Since private networks are generally blocked from the console, see the terraform steps above.
 
-Depending on your setup, you may need to either setup a windows server or submit API calls directly from code from trusted sources.
+If you are not blocked from the console, the only change to make from the default deployment is to set **Load Balancer Visibility** to **Private** which is under the **Public Endpoints** section.

…ts_to_private_networks/example_tfvars.md …te_networks/example_blueprints_tfvars.mddocs/advanced/deploying_blueprints_to_private_networks/example_tfvars.md renamed to docs/advanced/deploying_blueprints_to_private_networks/example_blueprints_tfvars.md docs/advanced/deploying_blueprints_to_private_networks/example_tfvars.md renamed to docs/advanced/deploying_blueprints_to_private_networks/example_blueprints_tfvars.md

@@ -9,6 +9,9 @@ corrino_admin_username = "admin" # use something else
 corrino_admin_nonce = "password" # use something else
 corrino_admin_email = "[email protected]"
 
+# If you want to authenticate with instance principal
+use_instance_principal = true
+
 # Leave these
 ingress_nginx_enabled = true
 cert_manager_enabled = false

docs/advanced/deploying_blueprints_to_private_networks/example_cluster_tfvars.md

@@ -0,0 +1,26 @@
+```
+# Your actual region
+region = "us-ashburn-1"
+tenancy_ocid = "ocid1.tenancy.oc1..aaaaaaaa____za"
+compartment_ocid = "ocid1.compartment.oc1..aaaaaaaa____5a"
+
+# If you want to authenticate with instance principal
+use_instance_principal = true
+
+network_configuration_mode = "bring_your_own"
+existing_vcn_id = "ocid1.vcn.oc1.iad.amaaaaaam____a"
+existing_endpoint_subnet_id = "ocid1.subnet.oc1.iad.aaaaaaaa____q"
+existing_node_subnet_id = "ocid1.subnet.oc1.iad.aaaaaaaa____q"
+existing_lb_subnet_id = "ocid1.subnet.oc1.iad.aaaaaaaa____q"
+k8s_version = "v1.31.1"
+cluster_workers_visibility = "Private"
+cluster_endpoint_visibility_existing_vcn = "Private"
+num_pool_workers = 3
+node_pool_name = "control-plane"
+node_pool_instance_shape = {
+  instanceShape = "VM.Standard.E3.Flex"
+  ocpus         = 6
+  memory        = 64
+}
+node_pool_boot_volume_size_in_gbs = 100
+```

oci_ai_blueprints_terraform/schema.yaml

@@ -508,9 +508,9 @@ variables:
   use_instance_principal:
     type: boolean
     title: "Use Instance Principal Authentication"
-    description: "Enable this to use Instance Principal authentication instead of user credentials. Requires the compute instance to have appropriate IAM policies."
+    description: "Terraform provider will use Instance Principal authentication instead of user credentials. Requires the compute instance to have appropriate IAM policies."
     default: false
-    visible: true
+    visible: false
 
   private_key_path:
     visible: false
@@ -1395,6 +1395,5 @@ outputs:
   use_instance_principal:
     type: boolean
     title: "Use Instance Principal Authentication"
-    description: "Enable this to use Instance Principal authentication instead of user credentials. Requires the compute instance to have appropriate IAM policies."
-    default: false
+    description: "Terraform provider will use Instance Principal authentication instead of user credentials. Requires the compute instance to have appropriate IAM policies."
     visible: true