Cloud Guru React-to-Kubernetes Deploy Pattern

Last updated: 27 July 2026

Take any containerisable front-end application from local development to a live Kubernetes cluster by following a repeatable three-stage pipeline: run locally, containerise with Docker, deploy on Kubernetes.

// TL;DR

The Cloud Guru React-to-Kubernetes Deploy Pattern is a repeatable three-stage pipeline for taking a containerisable React (or Node-based) app from local development to a live Kubernetes cluster: Run Locally → Containerise with Docker → Deploy on Kubernetes. Use it whenever you need to deploy a React app to a managed Kubernetes provider like IBM Cloud. Each stage must be validated before moving to the next — never skip to Kubernetes without confirming the Docker image works locally. The pattern enforces critical contracts like Port Consistency (Dockerfile port must match the kubectl expose port) and keeping API calls in the Redux Actions layer.

Framework

// When should you use the React-to-Kubernetes deploy pattern?

Use this skill whenever you need to containerise a React (or similar Node-based) application and deploy it to a Kubernetes cluster, whether on IBM Cloud or any equivalent managed Kubernetes provider.

// What do you need before deploying a React app to Kubernetes?

Application source coderequired
A React (or Node-based) application repository, ideally with an existing Dockerfile.
External API keyrequired
Any third-party API key the application depends on (e.g. an OMDB-style movie API key). Must be obtained and inserted into the actions/config layer before any stage.
Docker usernamerequired
Your Docker Hub (or container registry) username, exported as an environment variable (DOCKER_USERNAME) so it can be referenced consistently across build and push commands.
Kubernetes namespacerequired
A pre-created namespace in your target Kubernetes cluster (e.g. on IBM Cloud). Create one if it does not already exist.
Kubernetes cluster namerequired
The name of your target cluster, needed to retrieve the public worker IP address in the expose step.
IBM Cloud region code
The region suffix for your IBM Cloud container registry endpoint (e.g. 'ng' for US South, 'eu' for Europe). Only required for the IBM Cloud variant of the deploy.

// What are the core principles of the React-to-Kubernetes pipeline?

Three-Stage Pipeline

Every deployment follows the same ordered stages — Run Locally → Containerise with Docker → Deploy on Kubernetes. Never skip to Kubernetes without first validating the image locally in Docker.

Container Registry Parity

When deploying to a managed Kubernetes service (e.g. IBM Cloud Kubernetes), the Docker image must be built and pushed inside that provider's own Container Registry, not just Docker Hub. The build command is essentially the same; only the target registry endpoint changes.

Port Consistency Contract

The port declared in the Dockerfile MUST match the port used in the kubectl expose command. Breaking this contract is the most common silent failure in the deploy step.

Components vs. Containers Architecture

In the React layer, Containers hold all logic (API calls, state, event handlers) while Components are purely presentational and logic-free, making them reusable across contexts. API calls live in the Redux Actions layer, not in components.

Environment Variable for Registry Identity

Export your container registry username as an environment variable (e.g. export DOCKER_USERNAME=yourname) once at the start of a session. Reference it in every subsequent build and tag command to ensure naming consistency and avoid manual typos.

NodePort vs. LoadBalancer

For initial deployments and first-timers, NodePort is sufficient to expose a service externally. LoadBalancer is for more complex production cases and can be migrated to later.

// How do you deploy a React app to Kubernetes step by step?

1
Obtain all prerequisites before touching any code
Secure the external API key from the relevant third-party provider. Install Node.js. Have Docker Desktop running. Export your Docker username as an environment variable: `export DOCKER_USERNAME=<your-username>`. This variable must persist for the entire session.
2
Clone the repository and install dependencies
Clone the target repo, cd into it, then run `npm install` (or `yarn`). This installs all Node modules. While waiting, verify the project structure: source code should separate /actions, /components, /containers, /reducers, and /store.
3
Insert the API key into the Actions layer
Locate the API call inside the Redux Actions file (not in a component). Paste the API key there. This is the only place it should live. Confirm the app has distinct action types for start, success, and error states to support future loading/skeleton UI patterns.
4
Build CSS and start the app locally
Run `npm run build:css` first to compile Sass to CSS, then `npm run start`. Verify the app loads in the browser at localhost and that the API returns data correctly. Do not proceed to Docker until local validation passes.
5
Build the Docker image
Run: `docker build -t $DOCKER_USERNAME/<image-name>:latest .` — The image name should match the repo name for clarity. Confirm the build completes successfully. Deprecated npm module warnings during build are acceptable as long as the build succeeds.
6
Verify the image exists and run the container locally
Run `docker images` and confirm your newly built image appears in the list. Then run the container: `docker run -p <host-port>:<container-port> $DOCKER_USERNAME/<image-name>`. Navigate to localhost:<host-port> to confirm the containerised app works identically to the local version.
7
Build the Docker image inside the target cloud Container Registry
For managed Kubernetes providers, you must rebuild the image within their registry. For IBM Cloud: `ibmcloud cr build -t registry.<region>.icr.io/<namespace>/<image-name>:latest .` Substitute your region code and namespace. This step is structurally identical to Step 5 but targets the cloud registry endpoint.
8
Create a Kubernetes Deployment from the registry image
Run: `kubectl create deployment <deployment-name> --image=registry.<region>.icr.io/<namespace>/<image-name>:latest`. Confirm with `kubectl get deployments`. The deployment name will be referenced in the next step.
9
Expose the Deployment as a NodePort Service
Run: `kubectl expose deployment <deployment-name> --type=NodePort --name=<service-name> --port=<app-port>`. The --port value MUST match the port declared in the Dockerfile. Use LoadBalancer type only if you need advanced traffic management; NodePort is sufficient for initial deployments.
10
Retrieve the cluster public IP and service NodePort
Get the worker public IP: `ibmcloud cs workers <cluster-name>` — copy the Public IP from the output. Get the NodePort: `kubectl describe service <service-name>` — locate the NodePort field value. The app is now accessible at `<Public-IP>:<NodePort>`. Verify in a browser.

// What do real React-to-Kubernetes deployments look like?

A developer has a React dashboard app that calls a weather API. They want to move it from running on their laptop to a publicly accessible Kubernetes cluster.

Follow the Three-Stage Pipeline: (1) insert the weather API key into the Redux Actions file, run locally to confirm data returns; (2) build and run a Docker image locally to confirm containerisation works; (3) rebuild the image in the cloud Container Registry, create a Kubernetes Deployment, expose it via NodePort, and access it at the cluster's Public IP + NodePort.

A team's React app works on Docker locally but returns no data when deployed to Kubernetes.

Apply the Port Consistency Contract check: compare the port in the Dockerfile EXPOSE instruction against the --port flag used in the kubectl expose command. A mismatch here is the most common silent failure. Also verify the API key is correctly embedded in the Actions layer — an invalid or missing key will cause data-fetch failures that appear as empty responses rather than errors.

// What mistakes should you avoid when deploying React to Kubernetes?

Skipping local validation before containerising — always confirm the app works with npm run start before building the Docker image.
Not exporting DOCKER_USERNAME as an environment variable before building, causing naming inconsistencies across build, tag, and push commands.
Inserting the API key in a Component or Container instead of the Redux Actions layer — this breaks the architecture pattern and makes key rotation harder.
Mismatching the port in the Dockerfile with the --port flag in kubectl expose — the app will silently fail to respond on the expected port.
Building the Docker image to Docker Hub only and then attempting to deploy it on a managed Kubernetes service that requires images to be in its own Container Registry (e.g. IBM Cloud CR).
Attempting to deploy to Kubernetes without first creating a namespace in the target cluster.
Skipping the `npm run build:css` step before starting — Sass will not be compiled and styles will be missing.

// What key terms should you know for React-to-Kubernetes deployment?

Code Pattern: IBM's term for a reference implementation repository that demonstrates a specific architectural or deployment approach, intended to be cloned and adapted.
Three-Stage Pipeline: The ordered deployment sequence: Run Locally → Containerise with Docker → Deploy on Kubernetes. Each stage must be validated before proceeding to the next.
Container Registry: The image storage service used by a cloud Kubernetes provider (e.g. IBM Cloud Container Registry). Images must be built and pushed here — not just to Docker Hub — before they can be deployed on the provider's Kubernetes service.
Components vs. Containers Architecture: A React/Redux structural pattern where Containers hold all business logic, state, and API-call dispatches, while Components are purely presentational and reusable with no embedded logic.
Actions Layer: The Redux Actions file — the single correct location for API calls and async logic. Defines action types for start, success, and error states to support loading UI patterns.
NodePort: A Kubernetes service exposure type that opens a specific port on every cluster worker node, making the service externally accessible. Recommended for initial deployments; LoadBalancer is the upgrade path for production.
Port Consistency Contract: The rule that the port declared in the Dockerfile EXPOSE instruction must exactly match the --port value in the kubectl expose command.
DOCKER_USERNAME: An environment variable exported at session start (export DOCKER_USERNAME=yourname) to ensure consistent image naming across all build, tag, and push commands.
Namespace: A logical partition within a Kubernetes cluster used to isolate resources. Must be created in the target cloud environment before deploying; referenced in container registry image paths.

// FREQUENTLY ASKED QUESTIONS

What is the React-to-Kubernetes deploy pattern?

It's a repeatable three-stage pipeline for deploying a React (or Node-based) app to a Kubernetes cluster: Run Locally → Containerise with Docker → Deploy on Kubernetes. Each stage must be validated before proceeding. It enforces contracts like matching your Dockerfile port to the kubectl expose port and keeping API calls in the Redux Actions layer.

What is the Port Consistency Contract in Kubernetes deployment?

The Port Consistency Contract is the rule that the port declared in your Dockerfile's EXPOSE instruction must exactly match the --port value in your kubectl expose command. Breaking this contract is the most common silent failure — the app deploys without errors but returns no data because it isn't listening on the expected port.

How do I deploy a React app to Kubernetes step by step?

First run the app locally with npm run build:css and npm run start to validate. Then build and run a Docker image locally to confirm containerisation. Finally, rebuild the image in your cloud Container Registry, create a Kubernetes Deployment, expose it via NodePort, then access it at the cluster's Public IP plus NodePort.

How do I fix a React app that works in Docker but returns no data on Kubernetes?

Check the Port Consistency Contract first — compare the Dockerfile EXPOSE port against the --port flag in your kubectl expose command; a mismatch is the most common silent failure. Also verify the API key is embedded in the Redux Actions layer, since an invalid or missing key causes empty responses that look like data-fetch failures rather than errors.

How does this pattern compare to just pushing to Docker Hub and deploying?

Unlike a generic Docker Hub push, this pattern enforces Container Registry Parity: managed Kubernetes services like IBM Cloud require the image to be built and pushed inside their own Container Registry, not just Docker Hub. It also mandates local validation at every stage, preventing the silent failures that generic 'build and deploy' approaches miss.

When should I use NodePort versus LoadBalancer for exposing my service?

Use NodePort for initial deployments and first-time setups — it opens a port on every worker node and is sufficient to expose your service externally. Upgrade to LoadBalancer only for production cases needing advanced traffic management. NodePort is the recommended starting point; you can migrate to LoadBalancer later without redesigning the pipeline.

When should I use the React-to-Kubernetes deploy pattern?

Use it whenever you need to containerise a React or similar Node-based application and deploy it to a Kubernetes cluster, whether on IBM Cloud or any equivalent managed provider. It's ideal for moving a locally-running front-end app to a publicly accessible cluster in a repeatable, validated way.

What results can I expect after following this pipeline?

You'll have a live React app accessible in a browser at your cluster's Public IP plus NodePort, backed by a validated Docker image stored in your cloud Container Registry and running as a Kubernetes Deployment. Because each stage is validated before the next, you'll catch containerisation and port issues locally rather than debugging them in production.

Where should API keys go in a React app being deployed?

API keys belong in the Redux Actions layer — the single correct location for API calls and async logic — not in a Component or Container. Placing the key here follows the Components vs. Containers architecture, keeps components purely presentational, and makes key rotation far easier during future deployments.

Why do I need to export DOCKER_USERNAME as an environment variable?

Exporting DOCKER_USERNAME once at session start ensures consistent image naming across every build, tag, and push command, avoiding manual typos. You reference it as $DOCKER_USERNAME in commands like docker build -t $DOCKER_USERNAME/image-name, so all your image references stay aligned throughout the session.

Do I need to create a namespace before deploying to Kubernetes?

Yes — you must have a pre-created namespace in your target cluster before deploying. The namespace isolates your resources and is referenced directly in your Container Registry image paths (e.g. registry.region.icr.io/namespace/image-name). Attempting to deploy without one is a common pitfall that blocks the pipeline.

// GET THIS SKILL — FREE