> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Optional Maia runner parameters

export const m_runner = "Maia runner";

export const maia = "Maia";

export const RunnerMetadata = ({runnerType, platforms = []}) => {
  return <div style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    paddingBottom: '14px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>Runner type</td>
            <td style={{
    paddingBottom: '14px',
    verticalAlign: 'middle'
  }}>{runnerType}</td>
          </tr>
          <tr>
            <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    whiteSpace: 'nowrap',
    verticalAlign: 'middle'
  }}>Runner platform</td>
            <td style={{
    verticalAlign: 'middle'
  }}>
              <div style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8px'
  }}>
                {platforms.map((platform, i) => <span key={i} style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
                    {platform} ✅
                  </span>)}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>;
};

<RunnerMetadata runnerType={`${maia} Hybrid`} platforms={["AWS", "Azure", "Google Cloud", "Snowflake"]} />

When creating a {m_runner}, there are a number of optional parameters that you may wish to set. These are listed on the **Runner details** screen under the heading **Optional parameters that may be required**. Optional parameters only need to be specified if you want to use the functionality they relate to.

To set optional parameters during {m_runner} creation, follow the instructions given in the appropriate document:

* [AWS setup](/docs/guides/aws-fargate-manual-runner-setup)
* [Azure setup](/docs/guides/azure-arm-runner-install#completing-the-installation)
* [Google Cloud setup](/docs/guides/gke-deployment-guide#phase-6-deploy-the-maia-runner-with-helm)

In the following sections, we describe {maia} functionality that requires optional parameters to be set.

Any changes to the optional parameters on an existing {m_runner} will require the {m_runner} to be restarted. Read [Restart a {m_runner}](/docs/guides/restart-runner) to learn more.

***

## Using a proxy server and custom certificates

While {m_runner}s don't interact with proxies by default, if your configuration requires a proxy then you should specify the following parameters.

| Parameter              | Description                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| PROXY\_HTTP            | Your HTTP proxy server and port. For example: `myproxy.com:3000`.                                                                       |
| PROXY\_HTTPS           | Your HTTPS proxy server and port. For example: `myproxy.com:3000`.                                                                      |
| PROXY\_PROTOCOL\_HTTP  | The protocol used by the HTTP proxy. Accepts `http` or `https`.                                                                         |
| PROXY\_PROTOCOL\_HTTPS | The protocol used by the HTTPS proxy. Accepts `http` or `https`.                                                                        |
| PROXY\_EXCLUDES        | Addresses the proxy should ignore. Separate multiple addresses using the pipe character, `\|`. For example: `website.com\|website.net`. |
| CUSTOM\_CERT\_LOCATION | The storage location for custom certificates. For example: `my_storage/my_certs`.                                                       |

Only the `.cer`, `.pem`, and `.crt` file types will be recognized as certificates. Any other file types in the storage location will be ignored by the {m_runner}.

For instructions on how to store certificate files and make them accessible to the {m_runner}, read [Storing external files](#storing-external-files), below.

<Note>
  Currently there is no functionality for handling proxy support in a Matillion [Full SaaS](/docs/guides/runner-overview#matillion-full-saas) environment.
</Note>

### Proxying AWS service and container traffic

When both AWS service traffic and container traffic must pass through a proxy, the following steps will be needed.

1. Deploy the service on an EC2 instance to gain more control over network configurations.
2. Export the proxy configuration at node level. Configure the EC2 instance to route all outbound traffic through the proxy.
3. Configure the proxy parameters on the {m_runner}, described above.

***

## Loading external drivers

The AWS, Azure, and Google Cloud hosted {m_runner}s natively include drivers for a large number of third-party connectors. There are, however, certain external drivers that aren't supplied by default. If a driver you need isn't supplied by default, you can upload your own drivers to the {m_runner} at runtime by specifying a storage location in your infrastructure that will hold the driver files. You specify the location in the following {m_runner} parameter.

| Parameter                  | Description                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| EXTERNAL\_DRIVER\_LOCATION | The storage location for any additional driver files. For example: `my_storage/my_drivers`. |

Only the `.jar` and `.so` file types will be recognized as external drivers. Any other file types in the storage location will be ignored by the {m_runner}.

For instructions on how to store these files and make them accessible to the {m_runner}, read [Storing external files](#storing-external-files), below.

<Note>
  * Adding additional unsupported drivers to the {m_runner} will result in increased startup time with no guarantee that they will work, so we don't recommend doing this. Supported drivers are listed [here](/docs/guides/uploading-external-drivers#drivers-needed-for-components).
  * Currently there is no support for importing external drivers to Matillion-hosted {m_runner}s in a [Full SaaS](/docs/guides/runner-overview#matillion-full-saas) environment.
</Note>

***

## Loading additional Python libraries

The [Python Script](/docs/components/python-script) component lets you import modules from any Python library. To do this, you need to install the packages into a local folder, then upload the packages from your local folder into an Amazon S3 or Azure Blob Storage location that is accessible to the {m_runner}, and lastly set the following parameter to point to the location. Uploading compressed packages directly to your cloud storage solution won't work.

| Parameter                    | Description                                                                                                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| EXTENSION\_LIBRARY\_LOCATION | The storage location of any additional Python libraries. For example: `my_storage/my_pythonlibs`. For Azure Blob Storage, this location must be the root of a container in your storage account. |

For instructions on how to store library files and make them accessible to the {m_runner}, read [Installing Python libraries](/docs/guides/installing-python-libraries).

***

## Export logs

Enable the following parameter to send {m_runner} logs to Matillion. This facilitates faster response if support is needed. For more details, read [Export logs](/docs/guides/export-logs-hybrid-saas).

| Parameter    | Description                                                                           |
| ------------ | ------------------------------------------------------------------------------------- |
| EXPORT\_LOGS | Set this to `true` to enable log export to Matillion. Defaults to `false` if not set. |

***

## Storing external files

For the {m_runner} to access external files (such as certificates or drivers), the files must be stored in an accessible location in your infrastructure. Follow the appropriate instructions, below, depending on whether your {m_runner} is hosted on [AWS](#aws-hosted-maia-runner), [Azure](#azure-hosted-maia-runner), or [Google Cloud](#google-cloud-hosted-maia-runner) infrastructure.

All files of one type must be stored in the same location. Different types may be stored in different locations, however. For example, all certificates must be stored together in one location pointed to by `CUSTOM_CERT_LOCATION`, while all Python libraries can be in a different location pointed to by `EXTENSION_LIBRARY_LOCATION`.

### AWS-hosted Maia runner

To make external files accessible to an AWS-hosted {m_runner}, store the files in an S3 bucket that's in the same account space as the {m_runner} and accessible by the {m_runner}.

The IAM role for the account the {m_runner} is hosted in will need to have at least the following permissions to access S3 buckets:

* `s3:ListAllMyBuckets`
* `s3:ListBucket`
* `s3:GetObject`
* `s3:GetBucketLocation`

These will be applied automatically if you created the {m_runner} using the provided [CloudFormation template](/docs/guides/runner-installation-cloudformation-quick-create).

Set the appropriate environment variables to point to the file location, as described above. For example, `s3://my-bucket/my-files`. You can optionally omit `s3://` from this, as the {m_runner} will assume the connection is to an S3 bucket and automatically use the correct protocol.

If you are updating an existing {m_runner}, you will need to create a new revision of the task definition in use, and add the environment variable with the appropriate path. Then, restart the service using the new task definition.

### Azure-hosted Maia runner

To make external files accessible to an Azure-hosted {m_runner}, store the files in an Azure Blob container in a storage account that's in the same resource group as the {m_runner} and accessible by the {m_runner}.

The storage account's managed identity associated with the {m_runner}'s container will need to have at least the following permissions:

* `Storage Account Contributor`
* `Storage Blob Data Contributor`
* `Storage Blob Data Reader`

These will be applied automatically if you create the {m_runner} using the provided [ARM template](/docs/guides/azure-arm-runner-install).

Set the appropriate environment variables to point to the file location, as described above. For example, `https://mystorageaccount.blob.core.windows.net/my-files`. You can optionally omit `https://` from this, as the {m_runner} will assume the connection is to a Blob container and automatically use the correct protocol.

If you are updating an existing {m_runner}, you will need to edit and deploy the existing container, and add the environment variable with the appropriate path. Then, create the new revision.

### Google Cloud-hosted Maia runner

To make external files accessible to a GKE-hosted {m_runner}, store the files in a GCS bucket that is accessible to the {m_runner}'s Workload Identity service account.

Grant the {m_runner}'s Workload Identity service account the following roles on the GCS bucket:

* `roles/storage.legacyBucketReader`
* `roles/storage.objectViewer`

The recommended way to grant these permissions is to add the bucket name to the `agent_gcs_buckets` Terraform variable and run `terraform apply`. This grants the required roles automatically. Read the [GCP IAM permissions guide](/docs/guides/gcp-iam-permissions-for-runner) for details.

Set the appropriate environment variable in your `values-gcp-prod.yaml` file to point to the file location. For example, `gs://my-bucket/my-files`. Then run `helm upgrade` to apply the change, as described in [Adding or updating GKE environment variables](#adding-or-updating-gke-environment-variables), below.

***

## Adding or updating AWS environment variables

To add a new environment variable or update an existing environment variable for an AWS-hosted {m_runner}, follow these steps:

1. Log in to your AWS account and navigate to the ECS service.
2. Select the ECS cluster name.
3. Click the **Task Definition** link name under the **Services** panel.
4. Click **Create New Revision**, then select **Create New Revision** in the list.
5. Add or update environment variables as needed.
6. Click **Create** to create a new task definition revision.
7. Return to the ECS cluster list and select the ECS cluster name.
8. Select the service name and click **Update**.
9. Select the **Force new deployment** checkbox.
10. Select the newly created revision version in the list.
11. Click **Update**.
12. Wait for the new task definition to start.

***

## Adding or updating Azure environment variables

To add a new environment variable or update an existing environment variable for an Azure-hosted {m_runner}, follow these steps:

1. Log in to the Azure portal and navigate to the container instances service.
2. Stop the running container instance.
3. Select the container instance from the list and click **Export template** on the left.
4. Click the **Deploy** icon after the template generation is complete.
5. Click the **Edit Template** link.
6. Add or update environment variables as needed.
7. Click **Save**.
8. Enter the resource group name and Log Analytics workspaces key details.
9. Click **Review + Create**.
10. Wait for the deployment to complete. A message saying "Deployment is in progress" will be displayed.
11. Once the deployment is complete, click the container instance name.
12. Click the containers on the left to review the environment variables.
13. Click the **Properties** tab to list all variables.

***

## Adding or updating GKE environment variables

Optional parameters for GKE-hosted {m_runner}s are set in the `dpcAgent.dpcAgent.env` block of your Helm values file (`values-gcp-prod.yaml`). To add or update an environment variable:

1. Open your `values-gcp-prod.yaml` file.
2. Locate the `dpcAgent.dpcAgent.env` block and add or update the relevant parameter.
3. Run `helm upgrade` to apply the change:

```bash theme={null}
helm upgrade RELEASE_NAME . \
  --namespace NAMESPACE \
  -f values-gcp-prod.yaml
```

Replace `RELEASE_NAME` and `NAMESPACE` with the values used during your original deployment (both default to `matillion-agent`).

<Note>
  Optional parameters that aren't in use must be explicitly set to empty strings (for example, `customCertLocation: ""`). Leaving them as template placeholders (for example, `<CustomCertLocation>`) will cause the {m_runner} to exit immediately on startup.
</Note>