Guide: Setting Up a Restricted-Access OpenShift Cluster for SAP EdgeLM with Service Mesh 2.x (Evaluation)

Updated

IMPORTANT: EXPERIMENTATION NOTICE

This guide provides a Service Mesh 2.x implementation for customers who want to experiment with the restricted access feature. Please note that this implementation is provided for experimentation purposes only and is not officially supported by SAP.

For production deployments, please use the Service Mesh 3.x implementation, which represents SAP's officially supported solution and future direction for this feature. The Service Mesh 3.x version provides the same restricted access capabilities with the latest service mesh architecture.

Service Mesh Version Status:

Table of Contents

Overview

This guide provides step-by-step instructions for onboarding a shared Red Hat OpenShift cluster into SAP Edge Lifecycle Management (ELM) using a restricted-privilege model. Instead of requiring full cluster-admin rights, ELM will use a dedicated Service Account with a precise, limited set of permissions. The official source of truth for this process is Content from me.sap.com is not included.SAP Note 3618713, and this guide serves as an extension of the information provided therein.

Intended Audience: This document is for Red Hat OpenShift Cluster Administrators responsible for preparing the cluster environment.

Prerequisites

Before beginning this setup, ensure you have completed the following requirements:

Required Access and Credentials

Software Requirements

  • Red Hat OpenShift Container Platform 4.12-4.18 (tested versions)
  • OpenShift CLI (oc) version matching your cluster
  • Red Hat OpenShift Service Mesh Operators installed:
    • Red Hat OpenShift Service Mesh (required)
    • Kiali Operator (optional - for service mesh visualization)
    • Red Hat OpenShift distributed tracing platform (optional - for distributed tracing)

Downloaded Resources

Pre-Installation Steps

  1. Install Service Mesh Operators by following Red Hat documentation
  2. Verify core operator installation:
   # Verify the required Service Mesh operator is installed
   oc get csv -n openshift-operators | grep servicemesh

   # Optional: Verify additional operators if you installed them
   oc get csv -n openshift-operators | grep -E "(kiali|jaeger)"
  1. Download and extract resources.zip from Content from me.sap.com is not included.SAP Note 3618713 to your working directory

Process Overview

The setup process consists of five main stages:

  1. Prepare Namespaces: Create and configure the dedicated namespaces where all components will reside.
  2. Configure Service Mesh: Deploy and customize the Red Hat OpenShift Service Mesh to manage network traffic.
  3. Apply Permissions (RBAC): Apply the specific, fine-grained permissions that the ELM Service Account needs to operate.
  4. Generate Kubeconfig File: Create a unique Kubeconfig file that authenticates using the newly created Service Account.
  5. Register the Cluster in ELM: Use the generated Kubeconfig to add the cluster as an Edge Node in the ELM user interface.

Step 1: Prepare Namespaces

First, create the required namespaces to isolate the application components. You'll also apply annotations to these namespaces, which are necessary for OpenShift's Security Context Constraints (SCCs). These annotations pre-assign specific User ID (UID) and group ID ranges, ensuring that pods run with the minimum required privileges.

This single block of commands will create all the required namespaces and apply the necessary security annotations and service mesh labels.

# --- Create all required namespaces ---
oc create namespace edgelm  
oc create namespace istio-gateways  
oc create namespace edge-icell  
oc create namespace edge-icell-secrets  
oc create namespace edge-icell-ela  
oc create namespace edge-icell-services

# --- Label namespaces for Service Mesh auto-injection ---
oc label namespace edgelm edge-icell edge-icell-ela edge-icell-services istio-gateways istio-injection=enabled edgelm.sap.com/product=edgelm
oc label namespace edge-icell-secrets edgelm.sap.com/product=edgelm

# --- Apply the necessary security annotations for SCCs ---
oc annotate namespace edgelm openshift.io/sa.scc.supplemental-groups="67000/1000" --overwrite
oc annotate namespace edge-icell openshift.io/sa.scc.uid-range="10000/100" --overwrite
oc annotate namespace edge-icell openshift.io/sa.scc.supplemental-groups="1000/100" --overwrite
oc annotate namespace edge-icell-ela openshift.io/sa.scc.uid-range="100000/1000" --overwrite
oc annotate namespace edge-icell-ela openshift.io/sa.scc.supplemental-groups="100002/1000" --overwrite
oc annotate namespace edge-icell-services openshift.io/sa.scc.uid-range="1000000/1000" --overwrite
oc annotate namespace edge-icell-services openshift.io/sa.scc.supplemental-groups="1000002/1000" --overwrite

Verify Step 1 Completion

Run these commands to confirm namespaces are correctly configured:

# Verify all namespaces exist and are Active
oc get namespaces | grep -E "(edgelm|edge-icell|istio-gateways)"

# Expected output: 6 namespaces listed, all showing "Active" status

# Verify Service Mesh labels are applied
oc get namespace edgelm -o yaml | grep -A 5 labels

# Expected: Should see istio-injection=enabled and edgelm.sap.com/product=edgelm

Continue to Step 2 only after all namespaces show "Active" status.

Step 2: Configure OpenShift Service Mesh

The SAP Note requires a service mesh to be present. This guide provides a specific, tested configuration for Red Hat OpenShift Service Mesh version 2.x. Support for Red Hat OpenShift Service Mesh 3.x is currently ongoing, and this document will be updated upon official validation.

Key Requirements:

The following steps will create the istio-system namespace, deploy the Service Mesh control plane, and then add your application namespaces to the mesh.

Note: The configurations provided below are general guidance for a standard Service Mesh 2.x deployment. If you need to make customized changes to the service mesh configuration, please refer to the official Red Hat OpenShift Service Mesh 2.x documentation for detailed customization options.

# --- Command 1. Create the Service Mesh control plane namespace ---
oc new-project istio-system

# --- Command 2: Create the ServiceMeshControlPlane in the 'istio-system' namespace ---
oc apply -f - <<EOF
apiVersion: maistra.io/v2
kind: ServiceMeshControlPlane
metadata:
  name: basic
  namespace: istio-system
spec:
  version: v2.6
  policy:
    type: Istiod
  telemetry:
    type: Istiod
  addons:
    prometheus:
      enabled: true
    kiali:
      enabled: false
    grafana:
      enabled: true
  security:
    identity:
      type: ThirdParty
  gateways:
    enabled: false
EOF

# --- Command 3: Create the ServiceMeshMemberRoll to add namespaces to the mesh ---
oc apply -f - <<EOF
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
  name: default
  namespace: istio-system
spec:
  members:
    - edgelm
    - edge-icell
    - istio-gateways  
    - edge-icell-services
    - edge-icell-secrets
    - edge-icell-ela
EOF

Wait for Service Mesh Control Plane to Be Ready

The Service Mesh control plane takes 5-10 minutes to deploy and become ready. You must wait for it to be ready before proceeding to Step 3.

# Wait for Service Mesh control plane to be ready (may take 5-10 minutes)
oc wait --for=condition=Ready smcp/basic -n istio-system --timeout=600s

# Verify all components are running
oc get pods -n istio-system

Expected output: All pods should show Running or Completed status.

Note: If your environment requires special configurations like HTTP/1.0 support or Client IP preservation, see the Appendix: Optional Service Mesh Configurations section at the end of this document.

Step 3: Apply Permissions (RBAC)

This step configures the necessary Role-Based Access Control (RBAC) permissions. It applies required Custom Resource Definitions (CRDs), an admission webhook, cluster-wide roles, and specific roles within each namespace.

Prerequisites for this step:

# Verify you're in the correct directory with the YAML files
ls *.yaml | head -5
# Expected: You should see files like cr-edgelm-cluster-admin.yaml, crd-*.yaml, etc.

Cluster-Wide Permissions

Important: Apply CRDs first, then ClusterRoles that reference them:

# Step 3.1: Apply Custom Resource Definitions (CRDs) first
oc apply -f crd-helms.yaml
oc apply -f crd-imagereplications.yaml
oc apply -f crd-replicationservices.yaml
oc apply -f crd-sapcloudconnectors.yaml
oc apply -f crd-sourceregistries.yaml
oc apply -f crd-systemmappings.yaml
oc apply -f crd-solacesoftwarebrokers.yaml

# Step 3.2: Apply ClusterRoles (these reference the CRDs above)
oc apply -f cr-edgelm-cluster-admin.yaml
oc apply -f crb-edgelm-cluster-admin.yaml

# Step 3.3: Apply the admission webhook (if required)
# NOTE: The webhook is OPTIONAL and only needed for high-availability environments
# For detailed webhook setup including certificate generation, see:
# [SAP Note 3618713](https://me.sap.com/notes/3618713), section "Admission webhook"
oc apply -f webhook-pod-initializer.yaml

Namespace-Specific Permissions

# --- Permissions for 'edgelm' namespace ---
oc apply -f role-edgelm-manage.yaml -n edgelm 
oc apply -f rb-edgelm-manage.yaml -n edgelm 
oc apply -f role-edgelm-admin.yaml -n edgelm
oc apply -f rb-edgelm-admin.yaml -n edgelm

# --- Permissions for 'istio-gateways' namespace ---
oc apply -f role-edgelm-manage.yaml -n istio-gateways 
oc apply -f rb-edgelm-manage.yaml -n istio-gateways 
oc apply -f role-istio-gateways-admin.yaml -n istio-gateways
oc apply -f rb-istio-gateways-admin.yaml -n istio-gateways

# --- Permissions for 'edge-icell' namespace ---
oc apply -f role-edgelm-manage.yaml -n edge-icell 
oc apply -f rb-edgelm-manage.yaml -n edge-icell 
oc apply -f role-edge-icell.yaml -n edge-icell
oc apply -f rb-edge-icell.yaml -n edge-icell
oc apply -f rb-edge-icell-admin.yaml -n edge-icell

# --- Permissions for 'edge-icell-ela' namespace ---
oc apply -f role-edgelm-manage.yaml -n edge-icell-ela
oc apply -f rb-edgelm-manage.yaml -n edge-icell-ela
oc apply -f role-edge-icell-ela.yaml -n edge-icell-ela
oc apply -f rb-edge-icell-ela.yaml -n edge-icell-ela
oc apply -f rb-edge-icell-ela-admin.yaml -n edge-icell-ela

# --- Permissions for 'edge-icell-secrets' namespace --- 
oc apply -f role-edgelm-manage.yaml -n edge-icell-secrets 
oc apply -f rb-edgelm-manage.yaml -n edge-icell-secrets 
oc apply -f rb-edge-icell-secrets-admin.yaml -n edge-icell-secrets

# --- Permissions for 'edge-icell-services' namespace ---  
oc apply -f role-edgelm-manage.yaml -n edge-icell-services 
oc apply -f rb-edgelm-manage.yaml -n edge-icell-services 
oc apply -f role-edge-icell-services.yaml -n edge-icell-services
oc apply -f rb-edge-icell-services.yaml -n edge-icell-services
oc apply -f rb-edge-icell-services-admin.yaml -n edge-icell-services

Step 4: Generate Kubeconfig File

These commands create the edgelm Service Account and generate a edgelm-kubeconfig file using a persistent, non-expiring token. ELM will use this file to authenticate to your cluster.

# --- 1. Create the 'edgelm' service account in the 'edgelm' namespace ---  
oc create sa edgelm -n edgelm

# --- 2. Create a secret to hold the long-lived service account token ---  
oc apply -n edgelm -f - <<EOF  
apiVersion: v1  
kind: Secret  
metadata:  
  name: edgelm-kubeconfig-token  
  annotations:  
    kubernetes.io/service-account.name: edgelm
type: kubernetes.io/service-account-token  
EOF

# --- 3. Extract the token and generate the Kubeconfig file ---  
export SECRET_NAME_SA=edgelm-kubeconfig-token  
export TOKEN_SA=$(oc get secret ${SECRET_NAME_SA} -n edgelm -ojsonpath='{.data.token}' | base64 -d)  
oc config view --raw --minify > edgelm-kubeconfig  
oc config unset users --kubeconfig=edgelm-kubeconfig
oc config set-credentials edgelm --kubeconfig=edgelm-kubeconfig --token=${TOKEN_SA}  
oc config set-context --current --kubeconfig=edgelm-kubeconfig --user=edgelm

echo "Kubeconfig file 'edgelm-kubeconfig' has been generated successfully."

# Test the kubeconfig file to ensure it works
oc --kubeconfig=edgelm-kubeconfig auth can-i list pods -n edgelm

# Expected output: "yes" - this confirms the kubeconfig works correctly

Verify Step 4 Completion

# Verify the service account exists
oc get sa edgelm -n edgelm

# Verify the secret exists and contains a token
oc get secret edgelm-kubeconfig-token -n edgelm -o yaml | grep "token:"

# Test authentication with the generated kubeconfig
oc --kubeconfig=edgelm-kubeconfig get namespaces | grep edgelm

# Expected: Should list edgelm namespace, confirming authentication works

Continue to Step 5 only after the kubeconfig test succeeds.

Step 5: Register the Cluster in ELM

You are now ready to add your cluster as a new Edge Node in the ELM UI.

  1. In the ELM UI, start the Add an Edge Node process.
  2. On the first stage, Provide Edge Node Details, enter a name for your Edge Node.
  3. ⚠️ CRITICAL: Check "Restricted Access to Kubernetes cluster" checkbox
    • You MUST select this checkbox
    • Without this, ELM will attempt to use cluster-admin privileges and the deployment will fail
  4. When prompted for the Kubeconfig, provide the contents of the edgelm-kubeconfig file you just created.
  5. Proceed with the rest of the configuration as guided by the UI.
Article Type