Skip to main content

Version Upgrade Guide

This guide explains how to update the Kubernetes applications in the AGENTIC STAR marketplace edition.

note

Environments on AGENTIC STAR Basic can be updated within v2.x. They cannot be updated to v3.x. To use v3.x, purchase AGENTIC STAR Advanced (v3.3.0 or later) and deploy it as a new environment. Basic environments updated to v3.x by other means, such as applying v3.x Helm charts with Method B, are not supported.

You can choose from two methods. Method A (self-update) is recommended for most cases.

MethodOverviewRecommended For
Method A: Self-update from the admin console (recommended)Select a target version from the "Version Management" page and execute. Each service is upgraded automatically in dependency order.Most regular updates
Method B: Manual update (CLI operations)Operate kubectl / helm directly to upgrade individual charts.When instructed by support (such as recovering services that failed in Method A)

From the "Version Management" page in the admin console, you can automatically upgrade to the next available version. Each service is upgraded sequentially in pre-defined dependency order, and you can review progress and results on screen.

A-1. Prerequisites​

  • You can sign in to the admin console (e.g., https://admin.<your-domain>) with administrator privileges
  • The umbrella chart (agentic-star-platform) is published in the official Helm repository
  • The upgrade controller (upgrade-controller) is running in the cluster

A-2. Open the Version Management page​

After signing in, click "Version Management" in the left sidebar.

Version Management page (before update)

The page shows:

  • Current version: The currently deployed platform version (e.g., v3.3.0) and deployed status
  • Available versions: The next upgradable version (with a "Next version" label) and a link to each version's release notes
  • Deployed charts: Current version and status of each sub-chart
note

The available versions list follows a sequential upgrade model. You cannot jump multiple versions ahead — you must apply each "Next version" in order.

A-3. Select an upgrade target​

In the "Available versions" section, click the "Select" button on the right side of the next version you want to upgrade to (e.g., v3.4.0).

A-4. Review release notes and changes​

The "Upgrade Analysis" page is displayed.

Upgrade Analysis page

You can review:

  • Release notes (new features, changes, security fixes, etc.)
  • How many charts will be updated out of the total
  • Auto-applied values (auto_set) and values requiring input (user_input) for each service
  • When user_input is present: An input form is shown. Enter values referring to the hint for each item.

After reviewing/entering values, click the "Execute Upgrade" button at the top right.

A-5. Confirm execution​

A confirmation modal is displayed.

Upgrade execution confirmation modal

Review the warning messages:

  • The number of charts to be upgraded
  • A warning if Helm-external changes are detected (re-application may be required)
  • Possible temporary impact on services during the upgrade

If everything looks good, click "Upgrade". To abort, click "Cancel".

A-6. Watch progress​

The upgrade starts and the progress page is displayed.

Upgrade in progress page

The page shows:

  • An overall progress bar
  • The chart currently being processed (Upgrading <chart-name>...)
  • Status of each chart (processing / completed / skipped / failed)
note

Charts that have no version change (already at target_version) are shown as skipped and helm upgrade is not executed.

You can close this page and the upgrade will continue, but keep it open if you want to monitor progress.

A-7. Confirm completion​

When all charts are processed, the completion screen is displayed.

Upgrade completion screen

Verify the following:

  • The header shows "✓ Upgrade Complete"
  • Summary: Succeeded / Skipped / Failed counts
    • Make sure Failed is 0
  • Status list of each chart

When a newer upgrade-controller is available, the upgrade-controller itself is updated first, and the new upgrade-controller continues updating the remaining services. The progress display may be interrupted briefly; keep the page open.

When done, click "Back to Version Management" to return to the version management page.

A-8. Verify after the update​

On the Version Management page, confirm that "Current version" reflects the new version.

Version Management after update

  • Current version: The new version is shown with deployed and Latest
  • Deployed charts: Each sub-chart is at the new version with deployed status

A-9. Troubleshooting​

SituationAction
The lock is not released and you cannot retryVerify that no other upgrade is in progress. If none is, restart the upgrade-controller with kubectl rollout restart deploy/upgrade-controller -n upgrade-controller; the lock is released when it starts. Then retry from the screen.
Some charts failedCheck the error message of the failed charts on the completion screen. Find and fix the cause from the Pod status (kubectl get pods -A) and Pod logs, then run the update to the same version again from the version management screen (failed charts are retried).
The progress page does not advance for a long timeCheck the upgrade-controller Pod logs (kubectl logs -n upgrade-controller deploy/upgrade-controller).
"Helm-external changes detected" warning appearsSettings applied manually after the previous upgrade may be overwritten. Re-apply your custom settings after completion.

A-10. Entry switch when updating to v3.4.0​

From v3.4.0, the entry of AGENTIC STAR (the part that receives requests from browsers and APIs) is NGINX Gateway Fabric. When you update from v3.3.x to v3.4.0 with Method A, the upgrade-controller switches the entry to NGINX Gateway Fabric after updating the services.

  • The address of the entry (IP address or host name) and the URLs do not change
  • The settings of the entry, such as the product's own certificate and the source IP restriction, are carried over from the current entry (ingress-nginx) (the certificate and other settings for your own domain are not carried over; see the note below)
  • If the external entry of KC (the authentication server) is open, that entry is switched as well
  • After the switch is verified, the previous entry (ingress-nginx) is stopped (its Pods are scaled to 0 and autoscaling is turned off)
caution

For tens of seconds right after the switch, some requests may fail. Run the update when usage is low.

If you have set up your own domain

The certificate and the settings for placing a CDN or load balancer in front, made by following the Domain Settings Guide, are on the Ingress used by the previous entry (ingress-nginx), so they stop working right after the switch (the DNS targets and the entry addresses do not change). Without further action, a certificate error occurs or the site cannot be reached.

If you have set up your own domain, run the update when usage is low, and right after the update, configure the certificate and other settings on the entry (NGINX Gateway Fabric) by following the Domain Settings Guide (v3.4.0 or later). The same warning is also shown on the upgrade analysis screen.

You can check the switch with the following commands.

curl
kubectl get svc -n ingress-nginx -l app.kubernetes.io/purpose \
-o custom-columns='NAME:.metadata.name,ENTRY:.spec.selector.gateway\.networking\.k8s\.io/gateway-name'
kubectl get deploy ingress-nginx-controller -n ingress-nginx
  • First command: if every row shows a name such as front or admin in ENTRY, the entry is NGINX Gateway Fabric (a row with <none> is still on ingress-nginx)
  • Second command: if READY is 0/0, ingress-nginx is stopped
SituationAction
entry failed on the completion screenNGINX Gateway Fabric was not ready, so the entry is still ingress-nginx and keeps working. Check the error message and fix the cause, then run the update to the same version again from the version management screen (updated services are skipped and the switch is retried)
You want to go back to ingress-nginxFrom v3.4.0, the entry of AGENTIC STAR is NGINX Gateway Fabric only, and going back to ingress-nginx is not recommended (ingress-nginx is no longer developed by the community, and no fixed versions are provided). If you need to go back, contact support
note

Environments where HTTP/2 was disabled by following the news can be updated as they are. After the switch, that setting is no longer used.

Method B (manual update) does not switch the entry. Update to v3.4.0 with Method A.


Method B: Manual Update (CLI operations)​

This procedure upgrades each chart individually using kubectl / helm.

caution

Method B does not add or change the setting values required by each version (which Method A applies automatically). Values that became required in the new version are not set, and services may fail to start. Use Method A normally, and use Method B only when instructed by support (such as recovering services that failed in Method A).

B-1. Prerequisites​

  • Connected to the cluster via kubectl
  • Helm v3 installed
  • Administrator privileges on the target cluster
note

In the marketplace environment, the Helm storage driver is set to configmap, so all helm commands must be prefixed with HELM_DRIVER=configmap.

B-2. Update flow​

  1. Download the new version of the umbrella Helm chart
  2. Extract it and check each service's version in Chart.yaml
  3. Download individual charts
  4. Update each service with helm upgrade --reuse-values
  5. Verify operation after the update

B-3. Download the umbrella Helm chart​

Download the latest umbrella chart from the public repository.

curl
# Download the umbrella chart (adjust the version as needed)
curl -O https://agtstrmarketplacecharts.blob.core.windows.net/charts/agentic-star-platform-3.3.0.tgz

# Extract
tar xzf agentic-star-platform-3.3.0.tgz

B-4. Check versions​

The extracted Chart.yaml contains the individual version for each service.

curl
cat agentic-star-platform/Chart.yaml

B-5. Download individual charts​

Add the Helm repository and download charts with the versions listed in Chart.yaml.

curl
# Add the AGENTIC STAR repository
helm repo add agenticai-prod https://agtstrmarketplacecharts.blob.core.windows.net/charts
helm repo update

# Download an individual chart (e.g., agenticai-admin 3.3.0)
helm pull agenticai-prod/agenticai-admin --version 3.3.0 -d charts/

B-6. Service list​

The following is the list of services included in the marketplace edition.

Application components​

Release NameNamespaceNotes
librechatagentic-star-frontMain application
librechat-authlibrechat-authAuthentication service
keycloak-extensionslibrechat-authAuthentication platform (Keycloak)
agenticai-adminagentic-star-adminAdmin console
agent-executoragent-executorAgent execution platform
agenticai-extapiagenticai-extapi-serviceExternal API
gate-servicesgate-servicesGateway and routing
db-migrationdb-migrationDatabase migration
agent-sandbox-controlleragent-sandbox-systemManagement of the agent execution environments (sandboxes)
mail-ingressmail-ingressMail receiving

Security and Infrastructure​

Release NameNamespaceNotes
extauth-serviceproxy-systemZero-trust authorization service
ingress-nginxingress-nginxIngress controller
cert-managercert-managerCertificates
qdrantqdrantVector DB
cluster-autoscalerkube-systemAutomatic node scaling (AWS only)

Monitoring and Operations​

Release NameNamespaceNotes
prometheus-operatormonitoringPrometheus monitoring stack
prometheus-adaptermonitoringMonitoring
lokiobservabilityLog storage
alloy-logsobservabilityLog collector
alloy-metricsobservabilityMetrics collector
k8s-monitoringobservabilityKubernetes monitoring
agenticai-observabilityobservabilityGrafana / Jaeger
agenticai-datadogagenticai-datadogDatadog integration (optional)
pvc-lifecycle-managerpvc-lifecycle-managerPVC lifecycle management

Platform initialization​

Release NameNamespaceNotes
init-platformlibrechat-authInitialization job (typically does not need updating)
upgrade-controllerupgrade-controllerVersion management

B-7. Update commands​

Basic pattern​

Most services can be updated with the following pattern. --reuse-values preserves all existing settings; only the image tag specified by --set-string "image.tag=..." is updated.

curl
export HELM_DRIVER=configmap

HELM_DRIVER=configmap helm upgrade <release-name> <chart-path> \
--namespace <namespace> \
--reuse-values \
--set-string "image.tag=<version>" \
--wait \
--timeout 10m

Application components​

librechat (main application):

curl
HELM_DRIVER=configmap helm upgrade librechat ./charts/agentic-star-front-3.3.0.tgz \
--namespace agentic-star-front \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m

librechat-auth (authentication service):

curl
HELM_DRIVER=configmap helm upgrade librechat-auth ./charts/agentic-star-auth-3.3.0.tgz \
--namespace librechat-auth \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m

keycloak-extensions (authentication platform):

curl
HELM_DRIVER=configmap helm upgrade keycloak-extensions ./charts/keycloak-extensions-3.3.0.tgz \
--namespace librechat-auth \
--reuse-values \
--set-string "keycloakx.image.tag=3.3.0" \
--wait \
--timeout 15m
caution

Set keycloakx.image.tag of keycloak-extensions to the same version as librechat-auth (agentic-star-auth).

agenticai-admin (admin console):

curl
HELM_DRIVER=configmap helm upgrade agenticai-admin ./charts/agenticai-admin-3.3.0.tgz \
--namespace agentic-star-admin \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m

agent-executor (agent execution platform):

curl
HELM_DRIVER=configmap helm upgrade agent-executor ./charts/agent-executor-3.3.0.tgz \
--namespace agent-executor \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 20m

agenticai-extapi (external API):

curl
HELM_DRIVER=configmap helm upgrade agenticai-extapi ./charts/agenticai-extapi-3.3.0.tgz \
--namespace agenticai-extapi-service \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m

gate-services (gateway):

curl
HELM_DRIVER=configmap helm upgrade gate-services ./charts/gate-services-3.3.0.tgz \
--namespace gate-services \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m

db-migration (database migration):

curl
HELM_DRIVER=configmap helm upgrade db-migration ./charts/db-migration-3.3.0.tgz \
--namespace db-migration \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m

agent-sandbox-controller (management of the agent execution environments):

curl
HELM_DRIVER=configmap helm upgrade agent-sandbox-controller ./charts/agent-sandbox-controller-3.3.0.tgz \
--namespace agent-sandbox-system \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 5m

mail-ingress (mail reception):

curl
HELM_DRIVER=configmap helm upgrade mail-ingress ./charts/mail-ingress-3.3.0.tgz \
--namespace mail-ingress \
--reuse-values \
--set-string "haraka.image.tag=3.3.0" \
--wait \
--timeout 15m

Security and infrastructure​

extauth-service (zero-trust authorization service):

curl
HELM_DRIVER=configmap helm upgrade extauth-service ./charts/extauth-service-3.3.0.tgz \
--namespace proxy-system \
--reuse-values \
--set-string "image.tag=3.3.0" \
--set-string "webhook.image.tag=3.3.0" \
--set cert-manager.enabled=false \
--wait \
--timeout 20m
caution

For extauth-service, also specify webhook.image.tag and always include cert-manager.enabled=false (cert-manager is installed separately).

ingress-nginx (Ingress controller):

curl
HELM_DRIVER=configmap helm upgrade ingress-nginx ./charts/ingress-nginx-4.14.0.tgz \
--namespace ingress-nginx \
--reuse-values \
--wait \
--timeout 10m

qdrant (vector DB):

curl
HELM_DRIVER=configmap helm upgrade qdrant ./charts/qdrant-3.3.0.tgz \
--namespace qdrant \
--reuse-values \
--wait \
--timeout 20m

Monitoring and operations​

prometheus-operator (Prometheus monitoring stack):

curl
HELM_DRIVER=configmap helm upgrade prometheus-operator ./charts/kube-prometheus-stack-79.5.0.tgz \
--namespace monitoring \
--reuse-values \
--wait \
--timeout 15m
note

The chart name is kube-prometheus-stack, but the release name is prometheus-operator.

loki (log storage):

curl
HELM_DRIVER=configmap helm upgrade loki ./charts/loki-6.37.0.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m

alloy-logs (log collector):

curl
HELM_DRIVER=configmap helm upgrade alloy-logs ./charts/alloy-1.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m

alloy-metrics (metrics collector):

curl
HELM_DRIVER=configmap helm upgrade alloy-metrics ./charts/alloy-1.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 20m
note

alloy-logs and alloy-metrics use the same chart (alloy-1.1.2.tgz) but with different release names and values.

k8s-monitoring (Kubernetes monitoring):

curl
HELM_DRIVER=configmap helm upgrade k8s-monitoring ./charts/k8s-monitoring-3.1.2.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 15m

agenticai-observability (Grafana / Jaeger):

curl
HELM_DRIVER=configmap helm upgrade agenticai-observability ./charts/agenticai-observability-3.3.0.tgz \
--namespace observability \
--reuse-values \
--wait \
--timeout 15m

agenticai-datadog (Datadog integration):

curl
HELM_DRIVER=configmap helm upgrade agenticai-datadog ./charts/agenticai-datadog-3.3.0.tgz \
--namespace agenticai-datadog \
--reuse-values \
--wait \
--timeout 10m

pvc-lifecycle-manager (PVC lifecycle management):

curl
HELM_DRIVER=configmap helm upgrade pvc-lifecycle-manager ./charts/pvc-lifecycle-manager-3.3.0.tgz \
--namespace pvc-lifecycle-manager \
--reuse-values \
--wait \
--timeout 10m

upgrade-controller (version management):

curl
HELM_DRIVER=configmap helm upgrade upgrade-controller ./charts/upgrade-controller-3.3.0.tgz \
--namespace upgrade-controller \
--reuse-values \
--set-string "image.tag=3.3.0" \
--wait \
--timeout 10m
note

The following external charts are not covered by Method B: prometheus-adapter, cert-manager, and cluster-autoscaler (AWS only). prometheus-adapter is updated by Method A. cert-manager and cluster-autoscaler keep the versions installed at deployment.

B-8. Verify after the update​

Check Pod status​

curl
# Check Pod status across all namespaces
HELM_DRIVER=configmap helm list -A

# Check Pods in a specific namespace
kubectl get pods -n <namespace>

Check logs​

Verify there are no errors after the update.

curl
# Check logs of a specific Pod
kubectl logs -n <namespace> <pod-name>

# Check recent events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Notes​

  • Update on a per-service basis. We recommend updating one service at a time and verifying, rather than all at once (Method A handles this internally).
  • Because we use --reuse-values, settings changed via the Domain Configuration Guide and Security Guide are preserved.
  • We recommend taking a backup before updating.
  • For versions that include database migrations, going back to the previous version's charts does not return the data to its previous form, so rollback may not be possible. Take a backup before updating, and contact support if problems occur.