Got it, let's break down how to fix your port conflict issue and set up a stripped-down K3s deployment with separate Docker containers for server and agent.

First, let's address your core pain points:

• The 6444 port occupied error happens because K3s server runs an embedded agent by default (even if you tried disabling it—we'll fix that explicitly).
• Using localhost:6443 for the agent's K3S_URL doesn't work unless containers share the host network (not ideal for isolation). A dedicated Docker network is cleaner and avoids port mapping headaches.

Step 1: Create a Dedicated Docker Network #

This lets server and agent containers communicate directly via DNS names, no host port dependencies:

docker network create k3s-minimal-network

Step 2: Launch the Minimal K3s Server #

We'll disable all non-essential components and ensure no embedded agent runs (this eliminates the 6444 port conflict):

docker run -d \
  --name k3s-server \
  --network k3s-minimal-network \
  --privileged \
  -e K3S_TOKEN=MYTOKEN \
  rancher/k3s:latest server \
  --disable-agent \          # Critical: Stops the server from running an embedded agent (fixes 6444 port use)
  --no-deploy servicelb \    # Disable default load balancer
  --no-deploy traefik \      # Disable default ingress controller
  --no-deploy metrics-server \ # Disable metrics collector
  --disable-cloud-controller \ # Disable cloud-specific controllers (unneeded for local)
  --disable-network-policy \ # Disable network policy enforcement (simplifies setup)
  --kube-apiserver-arg="secure-port=6443" # Explicitly set API server port (avoids surprises)

Key Notes: #

• --privileged is required for K3s to handle network and storage operations inside the container.
• --disable-agent is the magic fix for your 6444 port issue: without this, the server container spins up an agent that claims port 6444 by default.

Step 3: Launch the K3s Agent #

Connect it to the server using the container name (resolvable via the dedicated Docker network):

docker run -d \
  --name k3s-agent \
  --network k3s-minimal-network \
  --privileged \
  -e K3S_TOKEN=MYTOKEN \
  -e K3S_URL=https://k3s-server:6443 \ # Use server container name instead of localhost
  rancher/k3s:latest agent \
  --disable-cloud-controller \ # Match the server's minimal config
  --kubelet-arg="port=10250" # Explicit kubelet port (avoids accidental conflicts)

Why This Fixes Connection Issues: #

• Using https://k3s-server:6443 lets the agent resolve the server directly via the Docker network—no host port mapping required.
• No overlap with host ports means you won't hit 6444 (or any other) port conflicts from processes running on your machine.

Step 4: Verify the Deployment #

Check if the agent registered successfully by running this command on the server container:

docker exec k3s-server kubectl get nodes

You should see two entries:

• k3s-server (status NotReady—this is expected, since we disabled its agent; it's just the control plane)
• k3s-agent (status Ready, your worker node)

Optional: Expose API Server to Your Host #

If you need to use kubectl on your local machine, add a port mapping to the server run command:

# Add this line to the server docker run command
-p 6443:6443

Then copy the kubeconfig from the server to your host:

docker cp k3s-server:/etc/rancher/k3s/k3s.yaml ~/.kube/config
# Replace "localhost" with your host IP in the kubeconfig file if needed

内容的提问来源于stack exchange，提问作者ricky116