# Oracle Kubernetes

This guide helps you connect Valohai with Oracle Kubernetes Engine (OKE).

## Prerequisites

**Tools:**

* kubectl - [installation guide](https://kubernetes.io/docs/reference/kubectl/)
* helm - [installation guide](https://helm.sh/docs/intro/install/#through-package-managers)
* oci-cli - [installation guide](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm#InstallingCLI__macos_homebrew)

**Oracle Cloud:**

* Oracle Cloud account
* Permissions to create and manage OKE clusters

## Step 1: Create the OKE Cluster

### Set Up the Cluster

**1. Navigate to cluster management**

Log in and navigate to <https://cloud.oracle.com/containers/clusters>

**2. Create cluster**

Click **Create cluster** and select **Quick Create**.

**3. Configure the cluster**

Official setup guide: [Oracle OKE Cluster Creation](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/create-cluster.htm)

**Configuration:**

* **Name:** Give your cluster a name
* **Endpoint:** Select **Public Endpoint** (unless in an air-gapped environment)
* **Worker type:** Select **Managed** (if utilizing an autoscaler)
* **Worker visibility:** Select **Private Workers**
* **Resources:** Pick the resources you wish to allocate, including number of nodes

**4. Review and create**

Proceed with the **Review** section and click **Create**.

## Step 2: Configure Local Access

### Set Up OCI CLI

Create the `.oci` directory and configure CLI access:

```shell
oci setup config
```

This command will prompt you for various OCIDs. Refer to [Oracle's documentation on finding OCIDs](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#five).

### Add Public Key to Oracle

**1. Generate and display the public key**

```shell
cat ~/.oci/oci_api_key_public.pem
```

**2. Copy the public key**

Copy the output of the command.

**3. Add to API Keys**

Add the public key to the API Keys associated with your Oracle profile.

Refer to [Oracle's documentation on API signing keys](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#three).

### Create kubeconfig File

Create the kubeconfig file with cluster and endpoint information:

```shell
oci ce cluster create-kubeconfig \
  --cluster-id <CLUSTER-OCID> \
  --file $HOME/.kube/_ociconfig \
  --kube-endpoint PUBLIC_ENDPOINT \
  --profile DEFAULT
```

**Parameters:**

* `--file $HOME/.kube/_ociconfig` - Specifies the location and creates the kubeconfig file
* `--kube-endpoint PUBLIC_ENDPOINT` - Generates config for a public endpoint
* `--profile DEFAULT` - Specifies the profile to use when interacting with Oracle Cloud

### Authenticate with Oracle CLI

Authenticate before proceeding with kubectl commands:

```shell
oci session authenticate
```

## Step 3: Install Kubernetes Workers

Install Valohai workers using Helm.

### Install with Helm

```shell
helm upgrade --install \
    -n valohai-workers \
    --create-namespace \
    valohai-workers \
    valohai/valohai-workers \
    -f ~/custom-values.yaml \
    --kubeconfig /Users/<REPLACE>/.kube/_ociconfig
```

Replace `<REPLACE>` with your username.

> **Note:** Reach out to the Valohai team at <support@valohai.com> to get your `custom-values.yaml` file.

### Custom Values File

The `custom-values.yaml` file contains:

```yaml
siteName: SITE_NAME
imagePullCredentials:
  email: EMAIL
  username: USERNAME
  password: PASSWORD
cleaner:
  sentryDsn: SENTRY_URL
```

These values will be provided by Valohai.

## Step 4: Complete Setup

### Send Information to Valohai

Securely send the output from the Helm command to Valohai support at **<support@valohai.com>**.

This allows Valohai to access the namespace of the cluster, which will finalize the process and enable Valohai to work with Oracle Kubernetes Engine.

### Information Needed

The Helm output should include:

* Namespace details
* Service account information
* Cluster access credentials

## Step 5: Verify the Setup

After Valohai confirms the environment is configured:

**1. Log in to app.valohai.com**

* Check that Oracle Kubernetes environments appear in your organization

**2. Run a test execution**

* Create a test project
* Run a simple execution
* Verify it runs on your OKE cluster

**3. Check results**

* Verify outputs are saved correctly
* Check execution logs

## Troubleshooting

### Cannot authenticate with OCI CLI

**Verify OCI configuration:**

```shell
cat ~/.oci/config
```

Check that all OCIDs and paths are correct.

**Test authentication:**

```shell
oci iam user get --user-id <YOUR-USER-OCID>
```

### kubeconfig not working

**Verify kubeconfig path:**

```shell
echo $KUBECONFIG
```

Should point to `/Users/<your-username>/.kube/_ociconfig`

**Test connection:**

```shell
kubectl get nodes --kubeconfig /Users/<your-username>/.kube/_ociconfig
```

### Helm installation fails

**Check namespace:**

```shell
kubectl get namespaces --kubeconfig /Users/<your-username>/.kube/_ociconfig
```

**Verify Helm can access cluster:**

```shell
helm list -n valohai-workers --kubeconfig /Users/<your-username>/.kube/_ociconfig
```

**Check custom-values.yaml:**

* Ensure all values are properly set
* Verify no syntax errors in YAML

### Pods not starting

**Check pod status:**

```shell
kubectl get pods -n valohai-workers --kubeconfig /Users/<your-username>/.kube/_ociconfig
```

**Check pod logs:**

```shell
kubectl logs <pod-name> -n valohai-workers --kubeconfig /Users/<your-username>/.kube/_ociconfig
```

**Common issues:**

* Image pull errors (check credentials)
* Insufficient resources (check node capacity)
* Network policies blocking traffic

## Additional Resources

**Oracle Documentation:**

* [OKE Cluster Management](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/create-cluster.htm)
* [API Signing Keys](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm)
* [OCI CLI Configuration](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm)

**Valohai Documentation:**

* [Kubernetes Workers Installation](/installation-and-setup/kubernetes/workers.md)

## Getting Help

**Valohai Support:** <support@valohai.com>

**Include in support requests:**

* Oracle Cloud region
* Cluster OCID
* kubectl version
* OCI CLI version
* Helm output or error messages
* Pod logs if available


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/installation-and-setup/kubernetes/oracle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.