Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Updated on June 15, 2020

Configure Kubernetes mode in NAT Manager

Use --nat-method=AUTO or --nat-method=KUBERNETES CLI options to let the Besu node automatically configure its IP address and ports.

Use mode --nat-method=NONE to be able to set your Besu ports and IP address manually.

Default mode is AUTO but Besu will fallback to NONE mode if automatic configuration fails.

Example

The following log shows fallback to NONE mode after an automatic detection failure.

INFO  | KubernetesNatManager | Starting kubernetes NAT manager.
DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK.
DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used
INFO  | NetworkRunner | Starting Network.

Automatic configuration

Follow 3 steps to configure Besu for automatic IP address and ports detection on Kubernetes:

  1. Create a load balancer
  2. Check if the load balancer is properly deployed
  3. Deploy Besu

1 - Create a load balancer

Deploy a LoadBalancer service for Besu to recover IP address and ports.

Example

Here is an example that you can customise with your own ports and routing rules.

---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: besu
    app.kubernetes.io/release: "1.0.0"
  name: besu
spec:
  ports:
  - name: "json-rpc"
    port: 8545
    targetPort: 8545
  - name: "rlpx"
    port: 30303
    targetPort: 30303
  selector:
    app.kubernetes.io/name: besu
    app.kubernetes.io/release: "1.0.0"
  type: LoadBalancer

This service example lists the rules for the different ports used by Besu (json-rpc andrlpx). The default value is used for discovery.

2 - Check if the load balancer is properly deployed

Verify the load balancer readiness before launching Besu.

Run kubectl describe services besu to check the service status.

The command should display the following information:

Name:                     besu
Namespace:                default
Labels:                   app.kubernetes.io/name=besu
                          app.kubernetes.io/release=1.0.0
Annotations:              kubectl.kubernetes.io/last-applied-configuration:
                            {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"labels":{"app.kubernetes.io/name":"besu","app.kubernetes.io/release":"1....
Selector:                 app.kubernetes.io/name=besu,app.kubernetes.io/release=1.0.0
Type:                     LoadBalancer
IP:                       --------
LoadBalancer Ingress:     ***<IP>***

The load balancer must have an IP address displayed in place of ***<IP>*** on the LoadBalancer Ingress line to be ready.

Run the kubectl describe services besu command again until the load balancer IP address appears in the output.

3 - Deploy Besu

When steps 1 and 2 are completed, deploy Besu using the following yaml example:

Example

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: besu-config
  labels:
    app.kubernetes.io/name: besu
    app.kubernetes.io/release: 1.0.0
data:
  BESU_LOGGING: "INFO"
  BESU_NETWORK: "dev"
  BESU_P2P_ENABLED: "true"
  BESU_RPC_HTTP_ENABLED: "true"
  BESU_RPC_HTTP_APIS: "eth,net,web3,debug,admin"
  KUBE_CONFIG_PATH: "/opt/besu/shared/kube-config"
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: besu
  labels:
    app.kubernetes.io/name: besu
    app.kubernetes.io/release: "1.0.0"
spec:
  replicas: 1
  strategy: {}
  template:
    metadata:
      creationTimestamp: null
      labels:
        app.kubernetes.io/name: besu
        app.kubernetes.io/release: "1.0.0"
    spec:
      containers:
      - name: besu
        image: "hyperledger/besu:latest"
        imagePullPolicy: Always
        ports:
          - containerPort: 8545
          - containerPort: 30303
        envFrom:
        - configMapRef:
            name: besu-config
      restartPolicy: Always
status: {}

Automatic detection errors

Important

Automatic detection error messages do not prevent you to use Besu.

Try the fix indicated for each error or use --nat-method=KUBERNETES CLI option and set IP address and port manually.

Possible errors messages for Kubernetes automatic detection failure:

Service not found error message

  • Error message: Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used
  • Cause: load balancer did start correctly or has the incorrect name.
  • Fix: check and modify load balancer yaml configuration and restart service.

Example error log

INFO  | KubernetesNatManager | Starting kubernetes NAT manager.
DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK.
DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Service not found. NONE mode will be used
INFO  | NetworkRunner | Starting Network.

Forbidden error message

  • Error message: Nat manager failed to configure itself automatically due to the following reason Forbidden. NONE mode will be used
  • Cause: Besu don’t have permission to list the services via the Kubernetes API to retrieve IP address and ports from the load balancer.
  • Fix: Give it the required permissions using Role-based access control.

    If you can’t manage permissions, define the IP address and ports manually with NONE mode

Example error log

INFO  | KubernetesNatManager | Starting kubernetes NAT manager.
DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK.
DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Forbidden. NONE mode will be used
INFO  | NetworkRunner | Starting Network.

Tip

For dev environment, the permission issue can be fixed by running kubectl create clusterrolebinding myapp-view-binding --clusterrole=admin --serviceaccount=default:default

This command should only be used on developement environment and not in production environment.

In production environment, require a finer management of permissions using Kubernetes Role-based access control.

Ingress not found error message

  • Error message: Nat manager failed to configure itself automatically due to the following reason Ingress not found. NONE mode will be used
  • Cause: Load balancer did not finish to recover an IP address.
  • Fix: Check that the load balancer is properly deployed before launching Besu.

Example error log

INFO  | KubernetesNatManager | Starting kubernetes NAT manager.
DEBUG | KubernetesNatManager | Trying to update information using Kubernetes client SDK.
DEBUG | NatService | Nat manager failed to configure itself automatically due to the following reason Ingress not found. NONE mode will be used
INFO  | NetworkRunner | Starting Network.
Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list besu@lists.hyperledger.org