Deploying Solution Blueprints with Helm

Deploying Solution Blueprints with Helm#

Solution Blueprints are provided as Helm charts. The recommended approach to deploy them is to pipe the output of helm template to kubectl apply -f -. We don’t recommend helm install, which by default uses a Secret to keep track of the related resources. This does not work well with Enterprise clusters that often have limitations on the kinds of resources that regular users are allowed to create.

To deploy the blueprint, run the following command:

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  | kubectl apply -f - -n $namespace

By default, Solution Blueprints run on AMD Instinct. Selected blueprints also support AMD Radeon (GPU) and AMD EPYC (CPU only), see the Solution Blueprint Catalog for which blueprints are available on each platform. To deploy on Radeon or EPYC, pass --set global.platform=<platform> to helm template, where <platform> is radeon or epyc. This applies the platform-specific AIM image and resource profile. Example for Radeon:

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  --set global.platform=radeon \
  | kubectl apply -f - -n $namespace

Note: The default EPYC AIM images are gated on Hugging Face and require a Hugging Face token, see Providing a Hugging Face token. For platform-specific values, resource sizing, and deployment examples, refer to the individual Solution Blueprint documentation.

Using an existing deployment or external LLM#

By default, any required AIMs are deployed by the Helm chart. If you already have a compatible AIM deployed, you can use that instead and reuse resources.

To use an existing deployment or external model, set the corresponding existingService value to that endpoint. For instance, with an LLM, set the value of llm.existingService. Then, any other values you pass in the llm mapping are simply ignored, and your existing service is used instead. You should use the Kubernetes Service name, or if the service is in a different namespace, you can use the long form <SERVICENAME>.<NAMESPACE>.svc.cluster.local:<SERVICEPORT>. If needed, you can pass a whole URL.

Full example command:

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
servicename="aim-llm-my-model-123456"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  --set llm.existingService=$servicename \
  | kubectl apply -f - -n $namespace

Providing a Hugging Face token#

AIM images download model weights from Hugging Face at startup. Gated models need a token with read access to the model repository.

1. Create a token at Hugging Face → Settings → Access Tokens. Copy it once; you will not be able to see it again. Open the model page on Hugging Face and request access if required.

2. Create the secret in the target Kubernetes namespace: Run the command below to create a Secret in the namespace where you deploy the Solution Blueprint. The Secret stores the Hugging Face token from step 1. In this example, the Secret name and the data key are both hf-token. Replace <YOUR_HF_TOKEN_HERE> with your token, assign your target namespace to the namespace variable, then run the command.

namespace="my-namespace"
kubectl create secret generic hf-token \
  --from-literal=hf-token="<YOUR_HF_TOKEN_HERE>" \
  -n $namespace

3. Deploy the Solution Blueprint: Use the usual helm template … kubectl apply flow, and set llm.env_vars.HF_TOKEN.name to the Secret name and llm.env_vars.HF_TOKEN.key to the key you used in --from-literal (in this example both are hf-token).

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  --set llm.env_vars.HF_TOKEN.name=hf-token \
  --set llm.env_vars.HF_TOKEN.key=hf-token \
  | kubectl apply -f - -n $namespace

Note: Some blueprints use a different Helm values prefix than llm (for example chatLLM, autocompleteLLM, or coderLLM). Use the same env_vars.HF_TOKEN.name and env_vars.HF_TOKEN.key pattern, but replace llm with that prefix. Example when the dependency alias is coderLLM:

--set coderLLM.env_vars.HF_TOKEN.name=hf-token and --set coderLLM.env_vars.HF_TOKEN.key=hf-token.

To see which prefix your blueprint uses, open its Chart.yaml in the public repository and check dependencies → alias. For example, Agentic RAG names the bundled AIM chart llm (Chart.yaml for agentic-rag).

Pulling the Helm charts#

To access the helm chart, its values.yaml, and any additional override files that may be distributed alongside the chart, simply helm pull the chart. The chart is a GZIP TAR archive, with a name that includes the version that you pulled. Thus this may require interactively checking the name of the TAR that you pulled.

An example pull and untar command:

chart="aimsb-my-chart"
helm pull oci://registry-1.docker.io/amdenterpriseai/$chart
# List the directory, the file will appear with a name like $chart-<version>.tgz
ls -lah .
version=1.2.3
tar -xzf $chart-$version.tgz
cd $chart

Using ephemeralStorage or different storageClasses#

The default storageClass in Solution Blueprints is mlstorage, which is the default for AMD Enterprise AI clusters. To avoid using a storageClass altogether, and fall back to ephemeral storage, override the storageClassName to null. Similarly, the storageClassName can be overridden to a different one to use a different storageClass.

For example:

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  --set llm.storage.ephemeral.storageClassName=null \
  | kubectl apply -f - -n $namespace

Deleting Solution Blueprint resources with Helm#

To remove a deployed Solution Blueprint, use the same helm template command with kubectl delete instead of kubectl apply. This ensures all resources created by the chart are cleanly removed.

name="my-deployment"
namespace="my-namespace"
chart="aimsb-my-chart"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart | kubectl delete -f - -n $namespace

Troubleshooting#

General#

Basic familiarity with kubectl and with cluster monitoring tools (for example k9s) makes troubleshooting easier. For example:

  • kubectl get pods: See which workloads are ready

  • kubectl describe pod <pod> -n <namespace>: Use Events at the bottom for image pull, scheduling, volume, and similar errors

  • kubectl logs <pod> -n <namespace>: Inspect application output once a container has run

  • kubectl exec -it <pod> -n <namespace> -- /bin/sh: Optional shell inside a running pod when the image provides one

Changing the AIM image and precision#

Some blueprints set a fixed AIM engine precision in their defaults (for example, llm-chat sets AIM_PRECISION for an fp8-oriented AIM profile). The same precision is not necessarily supported or appropriate for every AIM image or hardware combination.

If you change the AIM image, read that blueprint’s values.yaml in the public repository and compare it with the model profiles and engine options documented in the aim-build repository, then align llm.env_vars.AIM_PRECISION with the AIM you intend to run.

Here is an example command that runs Mistral Small 24B with fp16 precision.

name="my-deployment"
namespace="my-namespace"
chart="aimsb-llm-chat"
helm template $name oci://registry-1.docker.io/amdenterpriseai/$chart \
  --set llm.image=amdenterpriseai/aim-mistralai-mistral-small-3-2-24b-instruct-2506:0.11.1 \
  --set llm.env_vars.AIM_PRECISION=fp16 \
  | kubectl apply -f - -n "$namespace"

GPU Availability#

The blueprint schedules workloads that request AMD Instinct GPUs. Before deploying, confirm that your cluster exposes allocatable GPU resources:

kubectl get nodes -o json | jq '.items[].status.allocatable'

On a node with GPUs configured, output includes an entry such as:

"amd.com/gpu": "1"

If Kubernetes does not expose the GPU, you might need to install the AMD GPU device plugin for Kubernetes:

kubectl apply -f https://raw.githubusercontent.com/ROCm/k8s-device-plugin/master/k8s-ds-amdgpu-dp.yaml
Contents