Build Configurations

Learn how to adjust and configure build for some advanced use-cases.

Using custom AWS IAM role

In some cases, a model needs to access external services during its build process.
If a build needs to access external AWS resources, a custom AWS IAM role can be passed to the Qwak build process.

The IAM role should be created with the following trust policy:

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<account-id>:root"
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": "arn:aws:iam::<account-id>:role/eksctl-Qwak-EKS-Cluster-nodegroup-*"
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<account-id>:root"
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": "arn:aws:iam::<account-id>:role/qwak-eks-base*"

For additional information on using custom AWS IAM roles please also visit the AWS Resources access dedicated page.

The IAM role ARN can be passed directly to a build using the --iam-role-arn flag. For example:

qwak models build \
    --model-id <model-id> \
    --iam-role-arn arn:aws:iam::<account-id>:role/<role-name> \

The Supplied IAM role ARN role can be accessed from the model code using the following code example:

from boto3

session = boto3.Session(profile_name='user-provided-role')
# Example for an S3 client:
s3 = session.client('s3')


In the provided code snippet, the profile name specified as user-provided-role is automatically associated by Qwak with your assumed IAM role. Therefore, there's no need to replace it in the code. This ensures seamless integration and access to AWS services within your model code.

Using GCP service account

In order to reach a GCP client resource make sure to create secret with you json service account. Once the secret key was created use the following flag to define it: --service-account-key-secret-name

Generating config files

To generate a config file from a command that you already use, specify the --outconf flag, which will print to the console a ready config based on the options you specified. For example assume you run the following command:

qwak models build \
    --model-id test_model \
    -T tag_1 -T tag_2 \
    -E VERSION=3.9 \

Here is an example of the output:

    base_image: qwak-base:0.0.18-cpu
    build_args: {}
    env_vars: ["OS=WINDOWS", "VERSION=3.9"]
    no_cache: true
    params: []
    aws_profile: null
    no_push: true
      conda_file: conda.yml
    git_credentials: null
    git_credentials_secret: null
    poetry: null
    qwak_sdk_extra_index_url: null
    virtualenv: null
    is_remote: false
      cpus: 2.0
      memory: 4Gi
  branch: main
  build_id: f139b71a-533a-11ec-a934-367dda8b746f
  model_id: test_model
    git_branch: master
    git_credentials: null
    git_credentials_secret: null
    main_dir: main
    uri: ~/model
  - tag1
  - tag2

To save the configuration into redirection , For example: qwak models build --model-id test_model ~/model --out-conf > config.yml

Customizing your build

Custom Docker image

You can use a custom Docker image for the build process. The custom base image will also be used for the serving image.

When executing a build, the image should be specified using the --base-image flag:

qwak models build \
    --model-id <model> \
    --base-image <image-id> \

<model-id> - The model ID associated with this build.
<image-id> - Docker image ID.
<uri> - Qwak-based model URI.

The custom docker image should be based on: or (in case of models requiring a GPU).

The Docker image entry point shouldn't be changed.

Custom Build Instance type

You can choose either ondemand or spot by using the flag --purchase-option. By default the remote build will run on spot. For exmaple:

qwak models build \
    --model-id <model> \
    --purchase-option ondemand \ 

Environment variables

Configuring environment variable in build and serving environment, The environment variables should specified with the flag -E when executing a build:

qwak models build \
    --model-id <model> \
    -E <key>=<value> -E <key>=<value> \

<model-id> - model id which the build should be related to.
<key> - Environment variable key.
<value> - Environment variable value.
<uri> - Qwak based model URI.


When you pass environment variables to the build process, their impact goes beyond just the build phase. These variables are not only propagated to the testing phase but are also 'baked' into the resulting image. As a result, they remain available during deployment, providing flexibility to overwrite them as needed. This enables seamless configuration management throughout the entire lifecycle of your application.

Passing secrets as environment variables

Qwak allows passing environment variables to model builds which receive values from Qwak secrets during the model build process.

While secret values will be accessible as environment variables during the build, they won't be displayed in the UI alongside other passed environment variables.

To implement this, you need to supply the environment variable value in the specified format: <key>=<secret.{secret-name}>.

For instance, if you have an API token stored under a Qwak secret named cloud_token and wish to pass it in the build under the environment variable APP_TOKEN, you would utilize the following command as an example:

qwak models build --model-id <model>  -E APP_TOKEN=secret.cloud_token <dest>


Note: Please note that the secrets must exist in the Qwak platform before running the above command.

Customizing main directory

Given the following Qwak-based model directory structure:

β”œβ”€β”€ main/
β”œβ”€β”€ tests/

You can change the main/ directorie’s name. For example, changing its name to iris_classifier/:

β”œβ”€β”€ iris_classifier/
β”œβ”€β”€ tests/ 

To configure the name in the main directory, use a build config as follows:

    main_dir: <new-directory-name>

So for the above example, the build config would be:

    main_dir: iris-classifier

Installing packages from PyPI

During the build process you can download and use packages from private repositories.

Create an environment variable PIP_EXTRA_INDEX_URL .


You can also send this data not in clear text, by creating local environment variables:



Fetching Model Code from a Private Git Repository

You can fetch model code from a private Git repository using either the --git-credentials-secret or --git-secret-ssh flags.

Using Token Credentials

  1. Generate a GitHub Access Token:

    • Navigate to GitHub > Settings > Developer settings > Personal access tokens > Generate new token.
    • Select the scopes you need for your project and generate the token.
  2. Create a Qwak Secret:

    • Use the format USERNAME:ACCESS_TOKEN to create a new Qwak secret.
    qwak secrets set --name '<your-qwak-secret>' --value "<username>:<access_token>"
  3. Build the Model:

    • Use the --git-credentials-secret flag to specify the name of this secret when building your model.
qwak models build \
  [email protected]:<git_user>/model-test.git#models/model/churn \
  --git-credentials-secret '<your-qwak-secret>' \
  --git-branch '<your-branch>'


The #models/model/churn part specifies the folder path where the model is located inside the repository.

Using SSH Authentication

  1. Generate an SSH Key:

    • If you don't have an SSH key, you can generate one using ssh-keygen -t rsa -b 4096 -C "[email protected]".
  2. Add SSH Key to GitHub:

    • Navigate to GitHub > Settings > SSH and GPG keys > New SSH key. Paste your public key and save.
  3. Create a Qwak Secret:

    • Copy your private SSH key to your clipboard:
    pbcopy < ~/.ssh/<your-private-key-file>
    • Create a new Qwak secret with the content of the copied private key.
    qwak secrets set --name '<your-qwak-secret>' --value "$(pbpaste)" 
  4. Build the Model:

    • Use the --git-secret-ssh flag to specify the name of this secret when building your model.
qwak models build \
  [email protected]:<git_user>/model-test.git#models/model/churn \
  --git-secret-ssh '<your-qwak-secret>' \
  --git-branch '<your-branch'