Configuration Placeholders#

Environment Specifications#

Note: Since this is a bare-metal single-node cluster without a cloud LoadBalancer (not GKE/EKS/AKS), services of type LoadBalancer created by the Istio IngressGateway will never receive an EXTERNAL-IP. This guide includes alternative access methods via port-forward and NodePort.

Prerequisites#

Before starting, make sure the following are in place:

• A single-node Kubernetes cluster in Ready state (see Kubernetes Single-Node Setup on AlmaLinux 9)
• kubectl configured and able to access the cluster (kubectl get nodes shows Ready)
• Sufficient resources on the node to run the Istio control plane + 4 Bookinfo microservices (at least 2 CPU / 4 GB RAM free is recommended)
• Internet access from the node (to download the Istio binary and pull container images)

Step 1: Download and Install istioctl#

1
curl -L https://istio.io/downloadIstio | sh -

1
Downloading istio-<ISTIO_VERSION> from https://github.com/istio/istio/releases/download/<ISTIO_VERSION>/istio-<ISTIO_VERSION>-linux-amd64.tar.gz ...
2

3
Istio <ISTIO_VERSION> download complete!
4

5
The Istio release archive has been downloaded to the istio-<ISTIO_VERSION> directory.
6

7
To configure the istioctl client tool for your workstation,
8
add the /home/user/istio-<ISTIO_VERSION>/bin directory to your environment path variable with:
9
         export PATH="$PATH:/home/user/istio-<ISTIO_VERSION>/bin"
10

11
Begin the Istio pre-installation check by running:
12
         istioctl x precheck

1
cd istio-*/

1
export PATH=$PWD/bin:$PATH
2

3
# To make it permanent, append to your shell profile
4
echo 'export PATH=$HOME/istio-<ISTIO_VERSION>/bin:$PATH' >> ~/.bashrc

1
istioctl version

1
Istio is not present in the cluster: no running Istio pods in namespace "istio-system"
2
1.31.0

Step 2: Install Istio with the Default Profile#

1
istioctl x precheck

1
✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
2
  To get started, check out https://istio.io/latest/docs/setup/getting-started/.

1
istioctl install --set profile=default -y

1
✔ Istio core installed ⛵️
2
✔ Istiod installed 🧠
3
✔ Ingress gateways installed 🛬
4
✔ Installation complete

Step 3: Verify the Installation#

1
kubectl get pods -n istio-system

1
NAME                                    READY   STATUS    RESTARTS   AGE
2
istio-ingressgateway-6dcdbcd758-z6mtb   1/1     Running   0          2m10s
3
istiod-84568cdf7c-tv9mt                 1/1     Running   0          2m24s

1
istioctl version

1
client version: 1.31.0
2
control plane version: 1.31.0
3
data plane version: 1.31.0 (1 proxies)

1
istioctl analyze -A

Step 4: Enable Automatic Sidecar Injection#

Istio automatically injects an Envoy sidecar proxy into every pod deployed in namespaces labeled with istio-injection=enabled.

1
kubectl label namespace default istio-injection=enabled

Verify the label:

1
kubectl get namespace -L istio-injection

Output:

1
NAME              STATUS   AGE     ISTIO-INJECTION
2
default           Active   4h29m   enabled
3
istio-system      Active   3m26s
4
kube-system       Active   4h29m
5
...

Step 5: Deploy the Bookinfo Application#

Bookinfo is Istio’s official sample application, consisting of 4 microservices (productpage, details, reviews, ratings) with 3 different versions of the reviews service (v1, v2, v3) — perfect for demonstrating traffic routing capabilities.

1
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml

1
kubectl get services

1
NAME          TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
2
details       ClusterIP   10.102.162.188   <none>        9080/TCP   7s
3
kubernetes    ClusterIP   10.96.0.1        <none>        443/TCP    4h30m
4
productpage   ClusterIP   10.111.175.168   <none>        9080/TCP   7s
5
ratings       ClusterIP   10.108.180.245   <none>        9080/TCP   7s
6
reviews       ClusterIP   10.99.206.200    <none>        9080/TCP   7s

1
kubectl get pods

1
NAME                              READY   STATUS    RESTARTS   AGE
2
details-v1-65bd58d55f-svxqk       2/2     Running   0          7m32s
3
productpage-v1-7498b5bd44-4s76z   2/2     Running   0          7m32s
4
ratings-v1-9bff6cb79-7zpjv        2/2     Running   0          7m32s
5
reviews-v1-54465994f9-47h5d       2/2     Running   0          7m32s
6
reviews-v2-577579b4c5-6vvfl       2/2     Running   0          7m32s
7
reviews-v3-6d7944df59-tlr6r       2/2     Running   0          7m32s

1
kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" \
2
  -c ratings -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"

1
<title>Simple Bookstore App</title>

1
kubectl apply -f samples/bookinfo/networking/bookinfo-gateway.yaml

1
gateway.networking.istio.io/bookinfo-gateway created
2
virtualservice.networking.istio.io/bookinfo created

1
kubectl get gateway

1
NAME               AGE
2
bookinfo-gateway   24s

Step 6: Expose Bookinfo on a Single-Node Cluster#

This is where the setup diverges from the official Istio documentation, which assumes your cluster has a cloud LoadBalancer. On a bare-metal single-node cluster, istio-ingressgateway will remain stuck in Pending:

1
kubectl get svc istio-ingressgateway -n istio-system

Output:

1
NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE
2
istio-ingressgateway   LoadBalancer   10.100.98.219   <pending>     15021:32283/TCP,80:32192/TCP,443:32707/TCP   12m

Choose one of the options below to access Bookinfo from outside the cluster.

1
kubectl port-forward -n istio-system svc/istio-ingressgateway 8080:80

1
http://<NODE_IP>:8080/productpage

1
kubectl patch svc istio-ingressgateway -n istio-system -p '{"spec": {"type": "NodePort"}}'

1
kubectl get svc istio-ingressgateway -n istio-system -o jsonpath='{.spec.ports[?(@.port==80)].nodePort}'

1
http://<NODE_IP>:<NODE_PORT>/productpage

Step 7: Confirm the App is Working#

Use curl to verify the application is accessible (example using port-forward from Option A):

1
curl -s "http://localhost:8080/productpage" | grep -o "<title>.*</title>"

Output:

1
<title>Simple Bookstore App</title>

Open the page in your browser and refresh several times — you’ll notice the reviews section cycling through different versions in round-robin fashion: no stars, black stars, and red stars. This happens because no routing rules have been applied yet, so traffic is distributed equally across all three versions.

Step 8: Define Service Versions with DestinationRules#

Before configuring traffic routing between reviews versions (e.g., request routing or traffic shifting), Istio needs to know which subsets/versions are available. This is done through DestinationRule resources.

1
kubectl apply -f samples/bookinfo/networking/destination-rule-all.yaml

Output:

1
destinationrule.networking.istio.io/productpage created
2
destinationrule.networking.istio.io/reviews created
3
destinationrule.networking.istio.io/ratings created
4
destinationrule.networking.istio.io/details created

Verify:

1
kubectl get destinationrules -o yaml

The default profile already enables auto mutual TLS, so you don’t need to set up mTLS manually for this demo.

Step 9: Kiali Dashboard — Visualizing Your Service Mesh#

Kiali is the official observability console for Istio. It provides a real-time visual representation of your service mesh topology, traffic flow, health status, and configuration validation. Istio ships Kiali as part of a bundle of observability addons alongside Prometheus (metrics), Grafana (dashboards), and Jaeger (distributed tracing).

1
kubectl apply -f samples/addons

1
serviceaccount/grafana created
2
configmap/grafana created
3
service/grafana created
4
deployment.apps/grafana created
5
configmap/istio-grafana-dashboards created
6
configmap/istio-services-grafana-dashboards created
7
deployment.apps/jaeger created
8
service/tracing created
9
serviceaccount/kiali created
10
configmap/kiali created
11
clusterrole.rbac.authorization.k8s.io/kiali created
12
clusterrolebinding.rbac.authorization.k8s.io/kiali created
13
service/kiali created
14
deployment.apps/kiali created
15
serviceaccount/prometheus created
16
configmap/prometheus created
17
service/prometheus created
18
deployment.apps/prometheus created
19
...

1
kubectl rollout status deployment/kiali -n istio-system

1
Waiting for deployment "kiali" rollout to finish: 0 of 1 updated replicas are available...
2
deployment "kiali" successfully rolled out

1
kubectl patch svc kiali -n istio-system -p '{"spec": {"type": "NodePort"}}'

1
kubectl get svc kiali -n istio-system -o jsonpath='{.spec.ports[?(@.port==20001)].nodePort}'

Step 10: Test Traffic Routing with VirtualServices#

Since the DestinationRules (with subsets v1/v2/v3) were applied in the previous step, you can now create a VirtualService to route 100% of traffic to a specific version. Let’s route all reviews traffic to v2 (black stars):

1
cat <<EOF | kubectl apply -f -
2
apiVersion: networking.istio.io/v1
3
kind: VirtualService
4
metadata:
5
  name: reviews
6
spec:
7
  hosts:
8
  - reviews
9
  http:
10
  - route:
11
    - destination:
12
        host: reviews
13
        subset: v2
14
EOF

Verify the routing rule:

1
kubectl get virtualservice reviews -o yaml

Refresh /productpage several times — now the reviews section will always show black stars (v2 fetches rating data but displays stars in black, unlike v3 which shows red stars). No more round-robin cycling between versions.

You can also confirm this in the Kiali graph — traffic to the reviews service now flows exclusively to the v2 subset, with no traffic going to v1 or v3:

Cleanup#

Once you’re done exploring, clean up all the resources:

1
# Remove Bookinfo and its gateway
2
samples/bookinfo/platform/kube/cleanup.sh
3

4
# (Optional) Revert services back to ClusterIP if you patched them to NodePort
5
kubectl patch svc istio-ingressgateway -n istio-system -p '{"spec": {"type": "ClusterIP"}}'
6

7
# Uninstall Istio from the cluster
8
istioctl uninstall --purge -y
9

10
# Delete the istio-system namespace
11
kubectl delete namespace istio-system

Troubleshooting#

References#

• Install with Istioctl — istio.io
• Bookinfo Application — istio.io
• Installation Configuration Profiles — istio.io
• Kiali — Service Mesh Observability
• Kubernetes Single-Node Setup on AlmaLinux 9 — im-gatan.com