Portal

Need

When helm upgrade --install returns, you need to confirm that the platform is usable, not only that Helm finished. This article lists the checks to run after an installation or an upgrade, in order, from the Kubernetes cluster to the first administrator using Data Management. For each check it gives the expected result and where to look when it fails.

Summarized Solution

1. The Helm release status is deployed.
2. Every pod is Running and ready.
3. Every Job left in the namespace is Complete.
4. The Welcome page opens at https://<site_name>.<domain> and redirects to the login page.
5. The first administrator receives the activation email.
6. The administrator completes the activation and can log in.
7. The administrator can open Platform Administration. A 404 error points to the ingress path in values.yaml.
8. The administrator grants themselves the Data Management roles, logs out and back in, and sees the Data Products section and the Data Management tools.

Detailed Solution

Set these variables first. <site_name> is the value of global.site_name (default selfhosted) and <domain> the value of global.domain. On OpenShift, you can use oc wherever this article uses kubectl.

export NAMESPACE=<SDP_NAMESPACE>
export RELEASE=<HELM_RELEASE_NAME>     # for example: sdp

helm list -n "$NAMESPACE"
helm status "$RELEASE" -n "$NAMESPACE"

kubectl get pods -n "$NAMESPACE"

# Only the pods that need attention
kubectl get pods -n "$NAMESPACE" --field-selector=status.phase!=Running,status.phase!=Succeeded

kubectl describe pod <POD_NAME> -n "$NAMESPACE"      # Events: image pull, missing Secret, probe failures
kubectl logs <POD_NAME> -n "$NAMESPACE" --all-containers

kubectl get jobs -n "$NAMESPACE"

Expected: every Job listed shows 1/1 completions and the status Complete.

Most setup Jobs are Helm hooks that are deleted once they succeed, so only a few remain in the namespace. A Job that is no longer listed after a deployed release has succeeded. You typically still see <release>-semarchy-iam-create-perm-admin-job-1, <release>-semarchy-iam-apply-config-1 and <release>-semarchy-iam-finalize-tf-apply, plus any diagnostic Job you created.

kubectl describe job <JOB_NAME> -n "$NAMESPACE"
kubectl logs job/<JOB_NAME> -n "$NAMESPACE"

export CJ=$(kubectl get cronjob -n "$NAMESPACE" -l k8s.semarchy.net/diagnostic-install-job=true -o jsonpath='{.items[0].metadata.name}')
kubectl create job -n "$NAMESPACE" --from=cronjob/$CJ semarchy-diagnostic-install-job
export JOB=$(kubectl get job -n "$NAMESPACE" -l k8s.semarchy.net/diagnostic-install-job=true -o jsonpath='{.items[0].metadata.name}')
kubectl wait --for=condition=complete job/$JOB -n "$NAMESPACE" --timeout 10m
export POD=$(kubectl get pod -n "$NAMESPACE" -l k8s.semarchy.net/diagnostic-sidecar=true -o jsonpath='{.items[0].metadata.name}')
export LATEST=$(kubectl exec -n "$NAMESPACE" "$POD" -- sh -c 'ls -1t /diagnostic-volume/support-bundle*.tar.gz 2>/dev/null | head -n1')
kubectl cp -n "$NAMESPACE" "$POD:$LATEST" ./support-bundle.tar.gz

4. The Welcome page is accessible

Open https://<site_name>.<domain> in a browser, for example https://selfhosted.platform.example.com.

Expected: the browser redirects to the login page served by Keycloak at https://<domain>/auth/…, with a valid certificate.

5. The activation email is received

At the end of the installation, the invite-site-admin Job asks Keycloak to send an activation email to the first administrator: the address set in tenant-settings.user_creation.email.

Expected: the email arrives within a few minutes. Its link is valid for 72 hours.

If it does not arrive:

• Check the spam or quarantine folder, and the logs of your SMTP relay.
• Check the mail-secret values: host, port, user, password, sender address, and the smtpSsl and smtpStartTls flags. Some services only accept a verified sender address, for example Amazon SES.
• Check that the address in tenant-settings.user_creation.email is correct.
• To send the email again, fix the cause and run the same helm upgrade --install command: the invitation Job runs on every upgrade and sends the email again as long as the administrator has not verified their address. Follow it with kubectl logs -f job/<release>-semarchy-data-platform-invite-site-admin -n "$NAMESPACE" while it runs.

6. The administrator can log in

Open the link in the email and complete the requested actions:

1. verify the email address;
2. set a password;
3. configure multi-factor authentication with an authenticator app (Authy, Google Authenticator, Microsoft Authenticator…) when the realm requires it;
4. accept the terms and conditions, if prompted.

Expected: you are logged in and redirected to Platform Administration.

If the link has expired, send the email again as described in step 5. If login fails after the actions, check the Keycloak pod logs.

7. The administrator can access Platform Administration

Open https://<site_name>.<domain>/admin, or the Platform Administration link from the Welcome page.

Expected: the Platform Administration page renders, with its Users section.

A 404 error on Platform Administration comes from the ingress path configured in values.yaml. Compare the site-admin ingress with the starter values file for your platform: the host must be <site_name>.<domain>, with the path /admin and pathType: Prefix.
site-admin:
  ingress:
    className: "<YOUR_INGRESS_CLASS_NAME>"
    hosts:
      - host: "<site_name>.<YOUR_GLOBAL_DOMAIN>"
        paths:
          - path: /admin
            pathType: Prefix
With another path type, such as ImplementationSpecific, or with no paths entry, the ingress controller does not route the /admin/… pages to the application. Check what was deployed with kubectl get ingress <release>-site-admin -n "$NAMESPACE" -o yaml. The same check applies to / (welcome), /user-profile and /log-explorer. Fix values.yaml and run helm upgrade --install again.