Deploying IBM Support for Hyperledger Fabric behind a firewall

Need to Know

• If you are deploying the IBM Support for Hyperledger Fabric behind a firewall, without access to the public internet, your JavaScript, or TypeScript smart contract will not be able to download external dependencies when it is deployed. You need to point to a local NPM registry for your smart contract to access the required dependencies. See Building Node.js Contracts with limited internet access. This problem does not occur if you are using smart contracts that are written in Go.

• After you deploy your peer and ordering nodes, you need to expose the ports of your nodes for your network to be able to respond to requests from applications or nodes outside your firewall. For more information about the ports that you need to expose, see Internet Ports in the security guide.

Kubernetes cluster does not download and update the latest version of IBM Support for Hyperledger Fabric automatically. To get the latest update, you need to create a new cluster and a new service instance.

Resources required

Ensure that your Kubernetes cluster has sufficient resources for the Fabric Operations Console and for the blockchain nodes that you create. The amount of resources that are required can vary depending on your infrastructure, network design, and performance requirements. To help you deploy a cluster of the appropriate size, the default CPU, memory, and storage requirements for each component type are provided in this table. Your actual resource allocations are visible in your blockchain console when you deploy a node and can be adjusted at deployment time or after deployment according to your business needs.

** These values can vary slightly. Actual VPC allocations are visible in the blockchain console when a node is deployed.

Note that when smart contracts are installed on peers that run a Fabric v2.x image, the smart contract is launched in its own pod instead of a separate container on the peer, which accounts for the smaller amount of resources required on the peer.

Browsers

The Fabric Operations Console has been successfully tested on the following browsers:

• Chrome Version 125.0.6422.141/142 (Official Build) (x86_64)
• Safari Version 17.5
• Firefox 126.0.1 (64-bit)

For known issue while accessing console URL using Chrome browser, please refer to Troubleshooting page.

Storage

In addition to a small amount of storage (10 GB) required by the Fabric Operations Console, persistent storage is required for each CA, peer, and ordering node that you deploy. Because blockchain components do not use the Kubernetes node local storage, network-attached remote storage is required so that blockchain nodes can fail over to a different Kubernetes worker node in the event of a node outage. And because you cannot change your storage type after deploying peer, CA, or ordering nodes, you need to decide the type of persistent storage that you want to use before you deploy any blockchain nodes.

The Fabric Operations Console uses dynamic provisioning to allocate storage for each blockchain node that you deploy by using a pre-defined storage class. You can choose your persistent storage from the available Kubernetes storage options. Each Storage Volume is provisioned with the RWO (Read Write Once) Access mode.

If the storage includes support for the volumeBindingMode: WaitForFirstCustomer setting, you should configure it to delay volume binding until the pod is scheduled. Read more in the Kubernetes Storage Classes documentation.

Before you deploy the IBM Support for Hyperledger Fabric, you must create a storage class with enough backing storage for the Fabric Operations Console and the nodes that you create. You can set this storage class to use the default storage class of your Kubernetes cluster or create a new class that is used by the Fabric Operations Console. If you are using a multizone cluster in IBM Cloud and you change the default storage class definition, then you must configure the default storage class for each zone.
After you create the storage class, run the following command to set the storage class of the multizone region to be the default storage class:

kubectl patch storageclass

If you prefer not to choose a persistent storage option, the default storage class of your namespace or OpenShift project is used. Host-local volume storage is not supported.

Before you begin

1. IBM Support for Hyperledger Fabric can be installed only on the Supported Platforms.

2. You need to install and connect to your cluster by using the kubectl CLI to deploy the platform.

3. If you are not running the platform on Red Hat OpenShift Container Platform or Red Hat Open Kubernetes Distribution, then you need to set up the NGINX Ingress controller and it needs to be running in SSL passthrough mode. For more information, see Considerations when using Kubernetes distributions.

4. If you have a Hardware Security Module (HSM) that you plan to use to generate and store the private key for your CA, peer, or ordering nodes, you need to create an HSM client image and push it to your container registry. Follow instructions in the advanced deployment topic to build the image.

Pull the IBM Support for Hyperledger Fabric images

You can download the complete set of IBM Support for Hyperledger Fabric images from the cpopen registry. To deploy the platform without access to the public internet, you need to pull the images and then push the images to a container registry that you can access from behind your firewall.

It is recommended to use the skopeo utility to download and copy your images to your local container registry. The skopeo tool is used for moving container images between different types of container storages. In order to download the platform images and copy them to your container registry behind a firewall, you first need to install skopeo.

The following commands only work with a Docker container registry. Depending on the level of permissions required for the target location for the images, you might need to prefix each command with sudo.

The platform recommends that you use the skopeo utility to download and copy your images to your local container registry. skopeo is a tool for moving container images between different types of container storages. In order to download the platform images and copy them to your container registry behind a firewall, you first need to install skopeo.

Run the following set of commands to download the images and push them to your registry.

Replace:

• <LOCAL_REGISTRY_USER> with the user ID with access to your container registry.
• <LOCAL_REGISTRY_PASSWORD> with the password to your container registry.

The following commands only work with a Docker container registry. Depending on the level of permissions required for the target location for the images, you might need to prefix each command with sudo.

skopeo copy docker://icr.io/cpopen/ibm-hlfsupport-operator:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-operator:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport-crdwebhook:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-crdwebhook:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-console:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-console:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-deployer:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-deployer:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport-mustgather:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-mustgather:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-init:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-init:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-enroller:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-enroller:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-couchdb:3.3.3-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-couchdb:3.3.3-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-ca:1.5.15-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-ca:1.5.15-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-grpcweb:1.0.9-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-grpcweb:1.0.9-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-orderer:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-orderer:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-utilities:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-utilities:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-peer:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-peer:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-chaincode-launcher:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-chaincode-launcher:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-ccenv:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-ccenv:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-goenv:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-goenv:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-nodeenv:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-nodeenv:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://icr.io/cpopen/ibm-hlfsupport/ibm-hlfsupport-javaenv:2.5.12-20251112-amd64 <LOCAL_REGISTRY>/ibm-hlfsupport-javaenv:2.5.12-20251112-amd64 -q --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all

After you complete these steps, you can use the following instructions to deploy the IBM Support for Hyperledger Fabric with the images in your registry.

Log in to your Kubernetes cluster

Before you can complete the next steps, you need to log in to your cluster by using the kubectl CLI. Follow the instructions for logging in to your cluster. If the command is successful, you can see the list of the namespaces in your cluster from your terminal by running the following command:

kubectl get pods

If successful, you can see the pods that are running in your default namespace:

docker-registry-7d8875c7c5-5fv5j    1/1       Running   0          7d
docker-registry-7d8875c7c5-x8dfq    1/1       Running   0          7d
registry-console-6c74fc45f9-nl5nw   1/1       Running   0          7d
router-6cc88df47c-hqjmk             1/1       Running   0          7d
router-6cc88df47c-mwzbq             1/1       Running   0          7d

Create the ibm-hlfsupport-infra namespace for the webhook

Because the platform has updated the internal apiversion from v1alpha1 in previous versions to v1beta1, a Kubernetes conversion webhook is required to update the CA, peer, operator, and console to the new API version. This webhook will continue to be used in the future, so new deployments of the platform are required to deploy it as well. The webhook is deployed to its own namespace, referred to as ibm-hlfsupport-infra throughout these instructions.

After you log in to your cluster, you can create the new ibm-hlfsupport-infra namespace for the Kubernetes conversion webhook using the kubectl CLI. The new namespace needs to be created by a cluster administrator.

Run the following command to create the namespace.

kubectl create namespace ibm-hlfsupport-infra

Set up the entitlement for a local registry

After you push the IBM Support for Hyperledger Fabric images to your own Docker registry, you need to store the password to that registry on your cluster by creating a Kubernetes Secret. Using a Kubernetes secret allows you to securely store the key on your cluster and pass it to the operator and the console deployments.

Run the following command to create the secret and add it to your ibm-hlfsupport-infra namespace or project:

kubectl create secret docker-registry cp-pull-secret --docker-server=<LOCAL_REGISTRY> --docker-username=<USER> --docker-password=<LOCAL_REGISTRY_PASSWORD> --docker-email=<EMAIL> -n <NAMESPACE>

• Replace <USER> with your username
• Replace <EMAIL> with your email address.
• Replace <LOCAL_REGISTRY_PASSWORD> with the password to your registry.
• Replace <LOCAL_REGISTRY> with the url of your local registry.
• Replace <NAMESPACE> with ibm-hlfsupport-infra.

The name of the secret that you are creating is cp-pull-secret. It is required by the webhook that you will deploy later. If you change the name of any of secrets that you create, you need to change the corresponding name in future steps.

Deploy the webhook and custom resource definitions (CRDs)

Before you can deploy a new instance of the platform to your Kubernetes cluster, you need to create the conversion webhook by completing the steps in this section. The webhook is deployed to its own namespace or project, referred to ibm-hlfsupport-infra throughout these instructions.

The first three steps are for deployment of the webhook. The last step is for the custom resource definitions for the CA, peer, orderer, and console components that IBM Support for Hyperledger Fabric requires. You only have to deploy the webhook and custom resource definitions once per cluster. If you have already deployed this webhook and custom resource definitions to your cluster, you can skip these four steps below.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: webhook
  namespace: ibm-hlfsupport-infra
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: webhook
rules:
- apiGroups:
  - "*"
  resources:
  - secrets
  verbs:
  - "*"
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: ibm-hlfsupport-infra
subjects:
- kind: ServiceAccount
  name: webhook
  namespace: ibm-hlfsupport-infra
roleRef:
  kind: Role
  name: webhook
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f rbac.yaml -n ibm-hlfsupport-infra

serviceaccount/webhook created
role.rbac.authorization.k8s.io/webhook created
rolebinding.rbac.authorization.k8s.io/ibm-hlfsupport-infra created

apiVersion: apps/v1
kind: Deployment
metadata:
  name: "ibm-hlfsupport-webhook"
  labels:
    helm.sh/chart: "ibm-hlfsupport"
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport-webhook"
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/instance: "ibm-hlfsupport-webhook"
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        helm.sh/chart: "ibm-hlfsupport"
        app.kubernetes.io/name: "ibm-hlfsupport"
        app.kubernetes.io/instance: "ibm-hlfsupport-webhook"
      annotations:
        productName: "IBM Support for Hyperledger Fabric"
        productID: "5d5997a033594f149a534a09802d60f1"
        productVersion: "1.0.9"
        productChargedContainers: ""
        productMetric: "VIRTUAL_PROCESSOR_CORE"
    spec:
      serviceAccountName: webhook
      imagePullSecrets:
        - name: cp-pull-secret
      hostIPC: false
      hostNetwork: false
      hostPID: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 2000
      containers:
        - name: "ibm-hlfsupport-webhook"
          image: "icr.io/cpopen/ibm-hlfsupport-crdwebhook:1.0.9-20251112-amd64"
          imagePullPolicy: Always
          securityContext:
            privileged: false
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 1000
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop:
                - ALL
              add:
                - NET_BIND_SERVICE
          env:
            - name: "LICENSE"
              value: "accept"
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: SERVICE_NAME
              value: ibm-hlfsupport-webhook
          ports:
            - name: server
              containerPort: 3000
          livenessProbe:
            httpGet:
              path: /healthz
              port: server
              scheme: HTTPS
            initialDelaySeconds: 30
            timeoutSeconds: 5
            failureThreshold: 6
          readinessProbe:
            httpGet:
              path: /healthz
              port: server
              scheme: HTTPS
            initialDelaySeconds: 26
            timeoutSeconds: 5
            periodSeconds: 5
          resources:
            requests:
              cpu: 0.1
              memory: "100Mi"

kubectl apply -n ibm-hlfsupport-infra -f deployment.yaml

deployment.apps/ibm-hlfsupport-webhook created

apiVersion: v1
kind: Service
metadata:
  name: "ibm-hlfsupport-webhook"
  labels:
    type: "webhook"
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport-webhook"
    helm.sh/chart: "ibm-hlfsupport"
spec:
  type: ClusterIP
  ports:
    - name: server
      port: 443
      targetPort: server
      protocol: TCP
  selector:
    app.kubernetes.io/instance: "ibm-hlfsupport-webhook"

kubectl apply -n ibm-hlfsupport-infra -f service.yaml

service/ibm-hlfsupport-webhook created

cat <<EOF | kubectl apply  -f -
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: ibpcas.ibp.com
  labels:
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport"
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        caBundle: "${TLS_CERT}"
        service:
          name: ibm-hlfsupport-webhook
          namespace: ibm-hlfsupport-infra
          path: /crdconvert
      conversionReviewVersions:
      - v1beta1
      - v1alpha2
      - v1alpha1
  group: ibp.com
  names:
    kind: IBPCA
    listKind: IBPCAList
    plural: ibpcas
    singular: ibpca
  scope: Namespaced
  versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: true
    subresources:
      status: {}
  - name: v1alpha2
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
  - name: v210
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: false
    storage: false
    subresources:
      status: {}
  - name: v212
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: false
    storage: false
    subresources:
      status: {}
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
status:
  acceptedNames:
    kind: IBPCA
    listKind: IBPCAList
    plural: ibpcas
    singular: ibpca
  conditions: []
  storedVersions:
  - v1beta1
EOF

customresourcedefinition.apiextensions.k8s.io/ibpcas.ibp.com created

customresourcedefinition.apiextensions.k8s.io/ibpcas.ibp.com configured

cat <<EOF | kubectl apply  -f -
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: ibppeers.ibp.com
  labels:
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport"
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        caBundle: "${TLS_CERT}"
        service:
          name: ibm-hlfsupport-webhook
          namespace: ibm-hlfsupport-infra
          path: /crdconvert
      conversionReviewVersions:
      - v1beta1
      - v1alpha2
      - v1alpha1
  group: ibp.com
  names:
    kind: IBPPeer
    listKind: IBPPeerList
    plural: ibppeers
    singular: ibppeer
  scope: Namespaced
  versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: true
    subresources:
      status: {}
  - name: v1alpha2
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
status:
  acceptedNames:
    kind: IBPPeer
    listKind: IBPPeerList
    plural: ibppeers
    singular: ibppeer
  conditions: []
  storedVersions:
  - v1beta1
EOF

customresourcedefinition.apiextensions.k8s.io/ibppeers.ibp.com created

customresourcedefinition.apiextensions.k8s.io/ibppeers.ibp.com configured

cat <<EOF | kubectl apply  -f -
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: ibpconsoles.ibp.com
  labels:
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport"
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        caBundle: "${TLS_CERT}"
        service:
          name: ibm-hlfsupport-webhook
          namespace: ibm-hlfsupport-infra
          path: /crdconvert
      conversionReviewVersions:
      - v1beta1
      - v1alpha2
      - v1alpha1
  group: ibp.com
  names:
    kind: IBPConsole
    listKind: IBPConsoleList
    plural: ibpconsoles
    singular: ibpconsole
  scope: Namespaced
  versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: true
    subresources:
      status: {}
  - name: v1alpha2
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
status:
  acceptedNames:
    kind: IBPConsole
    listKind: IBPConsoleList
    plural: ibpconsoles
    singular: ibpconsole
  conditions: []
  storedVersions:
  - v1beta1
EOF

customresourcedefinition.apiextensions.k8s.io/ibpconsoles.ibp.com created

customresourcedefinition.apiextensions.k8s.io/ibpconsoles.ibp.com configured

cat <<EOF | kubectl apply  -f -
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: ibporderers.ibp.com
  labels:
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport"
spec:
  conversion:
    strategy: Webhook
    webhook:
      clientConfig:
        caBundle: "${TLS_CERT}"
        service:
          name: ibm-hlfsupport-webhook
          namespace: ibm-hlfsupport-infra
          path: /crdconvert
      conversionReviewVersions:
      - v1beta1
      - v1alpha2
      - v1alpha1
  group: ibp.com
  names:
    kind: IBPOrderer
    listKind: IBPOrdererList
    plural: ibporderers
    singular: ibporderer
  scope: Namespaced
  versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: true
    subresources:
      status: {}
  - name: v1alpha2
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: false
    subresources:
      status: {}
status:
  acceptedNames:
    kind: IBPOrderer
    listKind: IBPOrdererList
    plural: ibporderers
    singular: ibporderer
  conditions: []
  storedVersions:
  - v1beta1
EOF

customresourcedefinition.apiextensions.k8s.io/ibporderers.ibp.com created

customresourcedefinition.apiextensions.k8s.io/ibporderers.ibp.com configured

Create a components namespace for your IBM Support for Hyperledger Fabric deployment

Next, you need to create a second project for your deployment of the IBM Support for Hyperledger Fabric. You (as a cluster administrator) can create a components namespace by using the kubectl CLI.

If you are using the CLI, create a new components namespace with the following command:

kubectl create namespace <NAMESPACE>

Replace <NAMESPACE> with the name for the IBM Support for Hyperledger Fabric deployment components namespace.

It is required that you create a components namespace for each blockchain network that you deploy with the IBM Support for Hyperledger Fabric. For example, if you plan to create different networks for development, staging, and production, then you need to create a unique namespace for each environment. Using a separate namespace provides each network with separate resources and allows you to set unique access policies for each network. You need to follow these deployment instructions to deploy a separate operator and console for each components namespace.

After creating the components namespace, overwrite the label as follows:

kubectl label --overwrite ns <NAMESPACE>  pod-security.kubernetes.io/enforce=baseline

You can also use the CLI to find the available storage classes for your namespace. If you created a new storage class for your deployment, that storage class must be visible in the output in the following command:

kubectl get storageclasses

If you are not using the default storage class, additional configuration is required. See Storage for the considerations.

Set up the entitlement for a namespace

You already set up entitlement for a local registry in the ibm-hlfsupport-infra namespace or project, now you need to create one in your IBM Support for Hyperledger Fabric namespace or project.

Run the following command to create the secret and add it to your namespace:

kubectl create secret docker-registry cp-pull-secret --docker-server=<LOCAL_REGISTRY> --docker-username=<USER> --docker-password=<LOCAL_REGISTRY_PASSWORD> --docker-email=<EMAIL> -n <NAMESPACE>

• Replace <USER> with your username
• Replace <EMAIL> with your email address.
• Replace <LOCAL_REGISTRY_PASSWORD> with the password to your registry.
• Replace <LOCAL_REGISTRY> with the url of your local registry.
• Replace <NAMESPACE> with the name of your project or namespace.

The name of the secret that you are creating is cp-pull-secret. This value is used by the operator to deploy the offering in future steps. If you change the name of any of secrets that you create, you need to change the corresponding name in future steps.

Add security and access policies

The IBM Support for Hyperledger Fabric requires specific security and access policies to be added to your namespace. The contents of a set of .yaml files are provided here for you to copy and edit to define the security policies. You must save these files to your local system and then add them your namespace by using the kubectl CLI. These steps need to be completed by a cluster administrator. Also, be aware that the peer init and dind containers that get deployed are required to run in privileged mode.

#*******************************************************************************
# © Copyright IBM Corporation 2021
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#*******************************************************************************

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: <NAMESPACE>
  labels:
    release: "operator"
    helm.sh/chart: "ibm-hlfsupport"
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport-operator"
rules:
- apiGroups:
  - apiextensions.k8s.io
  resources:
  - persistentvolumeclaims
  - persistentvolumes
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - apiextensions.k8s.io
  resources:
  - customresourcedefinitions
  verbs:
  - get
- apiGroups:
  - route.openshift.io
  resources:
  - routes
  - routes/custom-host
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - ""
  resources:
  - pods
  - pods/log
  - persistentvolumeclaims
  - persistentvolumes
  - services
  - endpoints
  - events
  - configmaps
  - secrets
  - nodes
  - serviceaccounts
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - "batch"
  resources:
  - jobs
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - "authorization.openshift.io"
  - "rbac.authorization.k8s.io"
  resources:
  - roles
  - rolebindings
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
  - bind
  - escalate
- apiGroups:
  - ""
  resources:
  - namespaces
  verbs:
  - get
- apiGroups:
  - apps
  resources:
  - deployments
  - daemonsets
  - replicasets
  - statefulsets
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - monitoring.coreos.com
  resources:
  - servicemonitors
  verbs:
  - get
  - create
- apiGroups:
  - apps
  resourceNames:
  - ibm-hlfsupport-operator
  resources:
  - deployments/finalizers
  verbs:
  - update
- apiGroups:
  - ibp.com
  resources:
  - ibpcas.ibp.com
  - ibppeers.ibp.com
  - ibporderers.ibp.com
  - ibpconsoles.ibp.com
  - ibpcas
  - ibppeers
  - ibporderers
  - ibpconsoles
  - ibpcas/finalizers
  - ibppeers/finalizers
  - ibporderers/finalizers
  - ibpconsoles/finalizers
  - ibpcas/status
  - ibppeers/status
  - ibporderers/status
  - ibpconsoles/status
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection
- apiGroups:
  - extensions
  - networking.k8s.io
  - config.openshift.io
  resources:
  - ingresses
  - networkpolicies
  verbs:
  - get
  - list
  - create
  - update
  - patch
  - watch
  - delete
  - deletecollection

kubectl apply -f ibm-hlfsupport-clusterrole.yaml -n <NAMESPACE>

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: <NAMESPACE>
  labels:
    release: "operator"
    helm.sh/chart: "ibm-hlfsupport"
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport-operator"
subjects:
- kind: ServiceAccount
  name: default
  namespace: <NAMESPACE>
roleRef:
  kind: ClusterRole
  name: <NAMESPACE>
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f ibm-hlfsupport-clusterrolebinding.yaml -n <NAMESPACE>

kubectl -n <NAMESPACE> create clusterrolebinding ibm-hlfsupport-operator-clusterrolebinding --clusterrole=<NAMESPACE> --group=system:serviceaccounts:<NAMESPACE>

Deploy the Hyperledger Fabric operator

The IBM Support for Hyperledger Fabric uses an operator to install the Fabric Operations Console. You can deploy the operator on your cluster by adding a custom resource to your namespace by using the kubectl CLI. The custom resource pulls the operator image from the Docker registry and starts it on your cluster.

Copy the following text to a file on your local system and save the file as ibm-hlfsupport-operator.yaml.

Replace image: icr.io/cpopen/ with image: <LOCAL_REGISTRY>/, insert the URL of your local registry.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ibm-hlfsupport-operator
  labels:
    release: "operator"
    helm.sh/chart: "ibm-hlfsupport"
    app.kubernetes.io/name: "ibm-hlfsupport"
    app.kubernetes.io/instance: "ibm-hlfsupport"
    app.kubernetes.io/managed-by: "ibm-hlfsupport-operator"
spec:
  replicas: 1
  strategy:
    type: "Recreate"
  selector:
    matchLabels:
      name: ibm-hlfsupport-operator
  template:
    metadata:
      labels:
        name: ibm-hlfsupport-operator
        release: "operator"
        helm.sh/chart: "ibm-hlfsupport"
        app.kubernetes.io/name: "ibm-hlfsupport"
        app.kubernetes.io/instance: "ibm-hlfsupport"
        app.kubernetes.io/managed-by: "ibm-hlfsupport-operator"
      annotations:
        productName: "IBM Support for Hyperledger Fabric"
        productID: "5d5997a033594f149a534a09802d60f1"
        productVersion: "1.0.0"
        productChargedContainers: ""
        productMetric: "VIRTUAL_PROCESSOR_CORE"
    spec:
      hostIPC: false
      hostNetwork: false
      hostPID: false
      serviceAccountName: default
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: kubernetes.io/arch
                    operator: In
                    values:
                      - amd64
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 2000
      imagePullSecrets:
        - name: cp-pull-secret
      containers:
        - name: ibm-hlfsupport-operator
          image: icr.io/cpopen/ibm-hlfsupport-operator:1.0.9-20251112-amd64
          command:
            - ibp-operator
          imagePullPolicy: Always
          securityContext:
            privileged: false
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: false
            runAsNonRoot: true
            runAsUser: 7051
            runAsGroup: 7051
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop:
                - ALL
              add:
                - CHOWN
                - FOWNER
          livenessProbe:
            tcpSocket:
              port: 8383
            initialDelaySeconds: 10
            timeoutSeconds: 5
            failureThreshold: 5
          readinessProbe:
            tcpSocket:
              port: 8383
            initialDelaySeconds: 10
            timeoutSeconds: 5
            periodSeconds: 5
          env:
            - name: WATCH_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: OPERATOR_NAME
              value: "ibm-hlfsupport-operator"
            - name: CLUSTERTYPE
              value: K8S
          resources:
            requests:
              cpu: 100m
              memory: 200Mi
            limits:
              cpu: 100m
              memory: 200Mi

• If you changed the name of the Docker key secret, then you need to edit the field of name: cp-pull-secret.

Then, use the kubectl CLI to add the custom resource to your namespace.

kubectl apply -f ibm-hlfsupport-operator.yaml -n <NAMESPACE>

Replace <NAMESPACE> with the name of your IBM Support for Hyperledger Fabric deployment namespace.

You can confirm that the operator deployed by running the command kubectl get deployment -n <NAMESPACE>. If your operator deployment is successful, then you can see the following tables with four ones displayed. The operator takes about a minute to deploy.

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
ibm-hlfsupport-operator   1/1     1            1           1m

Deploy the Fabric Operations Console

When the operator is running on your namespace, you can apply a custom resource to start the Fabric Operations Console on your cluster. You can then access the console from your browser. You can deploy only one console per Kubernetes namespace.

Save the custom resource definition below as ibm-hlfsupport-console.yaml on your local system:

apiVersion: ibp.com/v1beta1
kind: IBPConsole
metadata:
  name: ibm-hlfsupport-console
spec:
  arch:
  - amd64
  license:
    accept: false
  serviceAccountName: default
  email: "<EMAIL>"
  password: "<PASSWORD>"
  registryURL: icr.io/cpopen/ibm-hlfsupport
  imagePullSecrets:
    - cp-pull-secret
  networkinfo:
    domain: <DOMAIN>
  storage:
    console:
      class: ""
      size: 5Gi
  usetags: true
  version: 1.0.0

Accept the license:

• Accept the IBM Support for Hyperledger Fabric license by replacing the license parameter accept: false with the text accept: true.

Specify the external endpoint information of the console in the ibm-hlfsupport-console.yaml file:

• Replace registryURL: icr.io/cpopen/ibm-hlfsupport with the URL of your local registry.
• Replace <DOMAIN> with the name of your cluster domain. You need to make sure that this domain is pointed to the load balancer of your cluster.

Provide the user name and password that is used to access the console for the first time:

• Replace <EMAIL> with the email address of the console administrator.
• Replace <PASSWORD> with the password of your choice. This password also becomes the default password of the console until it is changed.

You may need to make additional edits to the file depending on your choices in the deployment process:

• If you changed the name of your Docker key secret, change corresponding value of the imagePullSecrets: field.
• If you created a new storage class for your network, provide the storage class that you created to the class: field.

Because you can only run the following command once, you should review the Advanced deployment options in case any of the options are relevant to your configuration before you install the console. For example, if you are deploying your console on a multizone cluster, you need to configure that before you run the following step to install the console.

After you update the file, you can use the CLI to install the console.

kubectl apply -f ibm-hlfsupport-console.yaml -n <NAMESPACE>

Replace <NAMESPACE> with the name of your IBM Support for Hyperledger Fabric deployment namespace. Before you install the console, you might want to review the advanced deployment options in the next section. The console can take a few minutes to deploy.

apiVersion: ibp.com/v1beta1
kind: IBPConsole
metadata:
  name: ibm-hlfsupport-console
spec:
  arch:
  - amd64
  license:
    accept: false
  serviceAccountName: default
  email: "<EMAIL>"
  password: "<PASSWORD>"
  registryURL: icr.io/cpopen/ibm-hlfsupport
  imagePullSecrets:
    - cp-pull-secret
  networkinfo:
    domain: <DOMAIN>
  storage:
    console:
      class: ""
      size: 5Gi
  clusterdata:
    zones:
  resources:
    console:
      requests:
        cpu: 500m
        memory: 1000Mi
      limits:
        cpu: 500m
        memory: 1000Mi
    configtxlator:
      limits:
        cpu: 25m
        memory: 50Mi
      requests:
        cpu: 25m
        memory: 50Mi
    couchdb:
      limits:
        cpu: 500m
        memory: 1000Mi
      requests:
        cpu: 500m
        memory: 1000Mi
    deployer:
      limits:
        cpu: 100m
        memory: 200Mi
      requests:
        cpu: 100m
        memory: 200Mi
  usetags: true
  version: 1.0.0

kubectl apply -f ibm-hlfsupport-console.yaml -n <NAMESPACE>

kubectl create secret generic console-tls-secret --from-file=tls.crt=./tlscert.pem --from-file=tls.key=./tlskey.pem -n <NAMESPACE>

apiVersion: ibp.com/v1beta1
kind: IBPConsole
metadata:
  name: ibm-hlfsupport-console
spec:
  arch:
  - amd64
  license:
    accept: false
  serviceAccountName: default
  email: "<EMAIL>"
  password: "<PASSWORD>"
  registryURL: icr.io/cpopen/ibm-hlfsupport
  imagePullSecrets:
    - cp-pull-secret
  networkinfo:
    domain: <DOMAIN>
  storage:
    console:
      class: default
      size: 10Gi
  usetags: true
  tlsSecretName: "<CONSOLE_TLS_SECRET_NAME>"

kubectl apply -f ibm-hlfsupport-console.yaml -n <NAMESPACE>

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
ibm-hlfsupport-operator   1/1     1            1           10m
ibm-hlfsupport-console     1/1     1            1           4m

kubectl get pods -n <NAMESPACE>

kubectl logs -f <pod_name> <container_name> -n <NAMESPACE>

kubectl logs -f ibm-hlfsupport-console-55cf9db6cc-856nz console -n blockchain-project

Log in to the console

You can use your browser to access the console by using the console URL:

https://<NAMESPACE>-ibm-hlfsupport-console-console.<DOMAIN>:443

• Replace <NAMESPACE> with the name of your IBM Support for Hyperledger Fabric deployment namespace.
• Replace <DOMAIN> with the name of your cluster domain. You passed this value to the DOMAIN: field of the ibm-hlfsupport-console.yaml file.

Your console URL looks similar to the following example:

https://blockchain-project-ibm-hlfsupport-console-console.xyz.abc.com:443

If you navigate to the console URL in your browser, you can see the console log in screen:

• For the User ID, use the value you provided for the email: field in the ibm-hlfsupport-console.yaml file.
• For the Password, use the value you encoded for the password: field in the ibm-hlfsupport-console.yaml file. This password becomes the default password for the console that all new users use to log in to the console. After you log in for the first time, you will be asked to provide a new password that you can use to log in to the console.

If you are unable to log in, ensure that you are not using the ESR version of Firefox. If you are, switch to another browser such as Chrome and log in. Otherwise, clear your browser cache and try logging in again.

The administrator who provisions the console can grant access to other users and restrict the actions they can perform. For more information, see Managing users from the console.

Next steps

When you access your console, you can view the nodes tab of your console UI. You can use this screen to deploy components on the cluster where you deployed the console. See the Build a network tutorial to get started with the console. You can also use this tab to operate nodes that are created on other clouds. For more information, see Importing nodes.

To learn how to manage the users that can access the console, view the logs of your console and your blockchain components, see Administering your console.

Considerations when using Kubernetes distributions

Before you attempt to install the IBM Support for Hyperledger Fabric on Azure Kubernetes Service, Amazon Web Services, Rancher, Amazon Elastic Kubernetes Service, or Google Kubernetes Engine, you should perform the following steps. Refer to your Kubernetes distribution documentation for more details.

1. Ensure that a load balancer with a public IP is configured in front of the Kubernetes cluster.

2. Create a DNS entry for the IP address of the load balancer.

3. Create a wild card host entry in DNS for the load balancer. This entry is a DNS A record with a wild card host.

   For example, if the DNS entry for the load balancer is test.example.com, the DNS entry would be:

   *.test.example.com
   

   that ultimately resolves to

   test.example.com
   

   When this host entry is configured, the following examples should all resolve to test.example.com:

   console.test.example.com
   peer.test.example.com
   

   You can use nslookup to verify that DNS is configured correctly:

   $ nslookup console.test.example.com
   

4. The DNS entry for the load balancer should then be used as the Domain name during the installation of IBM Support for Hyperledger Fabric.

5. The NGINX ingress controller must be used. See the ingress controller installation guide that can be used for most Kubernetes distributions. If you are using IBM Cloud Kubernetes Service, then refer to these instructions for specific configuration information.

6. Use the following instructions to edit the NGINX ingress controller deployment to enable ssl-passthrough or refer to the Kubernetes instructions.

   This example might not be exact for your installation. The key is to ensure the last line that enables ssl-passthrough is present.

   /nginx-ingress-controller
   --configmap=$(POD_NAMESPACE)/nginx-configuration
   --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
   --udp-services-configmap=$(POD_NAMESPACE)/udp-services
   --publish-service=$(POD_NAMESPACE)/ingress-nginx
   --annotations-prefix=nginx.ingress.kubernetes.io
   --enable-ssl-passthrough=true
   

7. Verify that all pods are running before you attempt to install the IBM Support for Hyperledger Fabric.

You can now resume your installation.

Considerations when using IBM Cloud Kubernetes Service

The IBM Support for Hyperledger Fabric service requires additional configuration when installing on IBM Kubernetes Platform (IKS). Additional steps are needed if a Virtual Private Cloud (VPC) is used. Also, the application load balancer (ALB) requires additional configuration.

kubectl get ingressclasses.networking.k8s.io

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: "k8s.io/ingress-nginx"

kubectl apply -f nginx.yaml

<alb*-id>: '{"enableSslPassthrough":"true", "ingressClass":"nginx"}'

kubectl get deploy -n kube-system <alb-id> -o yaml

containers:
      - args:
        - /nginx-ingress-controller
        - --configmap=kube-system/ibm-k8s-controller-config
        - --annotations-prefix=nginx.ingress.kubernetes.io
        - --default-ssl-certificate=default/community-ingress-ibm-hlfsupport-68e10f583f026529fe7a89da40169ef4-0000
        - --ingress-class=nginx
        - --http-port=80
        - --https-port=443
        - --enable-ssl-passthrough=true
        - --default-backend-service=kube-system/ibm-k8s-controller-default-backend
        - --tcp-services-configmap=kube-system/tcp-services
        - --publish-service=kube-system/public-crbukohphd0ps6erapoulg-alb1