# Deploy a self-hosted Soda Agent from Soda's private container registry ## What has changed? As of July 2025, the container images required for the self-hosted Soda agent will be distributed using private registries, hosted by Soda. EU cloud customers will use the EU registry located at `registry.cloud.soda.io`. US cloud customers will use the US registry located at `registry.us.soda.io`. The images currently distributed through Docker Hub will stay available there. New releases will only be available in the Soda-hosted registries. Existing or new Soda cloud API keys can be used to authenticate to the Soda-hosted registries. Starting from version `1.2.0`, the `soda-agent` Helm chart supports working with Soda-hosted image registries. In order to enjoy the latest features Soda has to offer, please upgrade any self-hosted Soda agent you manage using one of the following guides. ## How-to's ### Registry access using your existing API key Follow the self-hosted Soda agent [upgrade](/soda-documentation/soda-v3/quick-start-sip/upgrade.md#upgrade-a-self-hosted-soda-agent) or [redeployment](/soda-documentation/soda-v3/quick-start-sip/upgrade.md#redeploy-a-self-hosted-soda-agent) guides. Don't execute the final `helm install` or `helm upgrade` step yet. Ensure you retrieve the `soda.apikey.id` and `soda.apikey.secret` values first, by using\ `helm get values -n ` . Now pass these values back to the upgrade command via the CLI: ```shell helm upgrade soda-agent/soda-agent --set soda.apikey.id=*** \ --set soda.apikey.secret=**** ``` Or by using a values file: ```shell > cat values-local.yaml soda: apikey: id: *** secret: *** > helm upgrade soda-agent soda-agent/soda-agent \ --values values-local.yml --namespace soda-agent ``` ### Registry access using a separate API key Ensure you have a new API key `id` and `secret` by following the [API key creation guide](/soda-documentation/soda-v3/use-case-guides/api-keys.md) . Follow the self-hosted Soda agent [upgrade](/soda-documentation/soda-v3/quick-start-sip/upgrade.md#upgrade-a-self-hosted-soda-agent) or [redeployment](/soda-documentation/soda-v3/quick-start-sip/upgrade.md#redeploy-a-self-hosted-soda-agent) guides. Don't execute the final `helm install` or `helm upgrade` step yet. Now pass the API keys to use for registry access in the upgrade command via the CLI, using the `imageCredentials.apikey.id` and `imageCredentials.apikey.secret` properties.\ Note that we're also still passing the `soda.apikey.id` and `soda.apikey.secret` values, which are still required for the agent to authenticate to Soda Cloud. ```shell helm upgrade soda-agent/soda-agent --set soda.apikey.id=*** \ --set soda.apikey.secret=**** --set imageCredentials.apikey.id=*** \ --set imageCredentials.apikey.secret=*** ``` Or when using a values file: ```shell > cat values-local.yaml soda: apikey: id: *** secret: *** imageCredentials: apikey: id: *** secret: *** > helm upgrade soda-agent soda-agent/soda-agent \ --values values-local.yml --namespace soda-agent ``` ### Using existing (external) secrets You can also use a self-managed, existing secret to authenticate to the Soda-hosted or your self-hosted private container registry, for example when mirroring container images. You can refer to existing secrets as follows for the CLI: ```shell helm upgrade soda-agent/soda-agent --set soda.apikey.id=*** \ --set soda.apikey.secret=**** --set existingImagePullSecrets[0].name=my-existing-secret # Mind the array and indexing syntax! ``` Or using a values file: ```shell > cat values-local.yaml soda: apikey: id: *** secret: *** existingImagePullSecrets - name: my-existing-secret > helm upgrade soda-agent soda-agent/soda-agent \ --values values-local.yml --namespace soda-agent ``` ### Using the US image registry When you're onboarded on the US region of Soda Cloud, you'll have to use the container registry associated with that region. You can alter the `soda.cloud.region` value to automatically render the correct container registry and Soda Cloud API endpoint. Simply follow any of the above instructions and include the `soda.cloud.region` value. To do so in the CLI: ```shell helm upgrade soda-agent/soda-agent --set soda.apikey.id=*** \ --set soda.apikey.secret=**** --set soda.cloud.region=us ``` Or using a values file: ```shell > cat values-local.yaml soda: apikey: id: *** secret: *** cloud: region: "us" > helm upgrade soda-agent soda-agent/soda-agent \ --values values-local.yml --namespace soda-agent ``` ## FAQ ### Mirroring images If you want to mirror the Soda images into your own registries, you'll need to log in to the appropriate container registry. This will allow you to pull the images into your custom container image registry. ```shell # For Soda Cloud customers in the EU region docker login registry.cloud.soda.io -u -p # For Soda Cloud customers in the US region docker login registry.us.soda.io -u -p ``` The following `values.yaml` file illustrates the changes required for the Helm release to work with mirrored images: ```yaml existingImagePullSecrets - name: my-existing-secret soda: apikey: id: *** secret: *** agent: image: repository: custom.registry.org/sodadata/agent-orchestrator scanLauncher: image: repository: custom.registry.org/sodadata/soda-scan-launcher contractLauncher: image: repository: custom.registry.org/sodadata/soda-contract-launcher hooks: image: repository: custom.registry.org/sodadata/soda-agent-utils ``` ### Do I have to upgrade? What if we can't do that right away? Your existing Soda agent deployments will continue to function. This does mean that your self-hosted agent will not be able to support features like collaborative data contracts and the fully revamped metric monitoring. The images hosted on Docker Hub, required to run the self-hosted agent, will remain there in their current state for a grace period of 6 months. There will be no more maintenance (updates, bug fixes, security patches) for the old self-hosted agent versions. --- # 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.soda.io/soda-documentation/soda-v3/quick-start-sip/deploy-a-self-hosted-soda-agent-from-sodas-private-container-registry.md?ask= ``` 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.