How to run TKEStack locally

This guide will walk you through deploying the full TKEStack on you local machine and allow you to play with the core components. It is highly recommended if you want to develop TKEStack and contribute regularly.

Prerequisites

OS Requirements

TKE supports running on Linux, Windows or macOS operating systems.

Docker

TKE requires Docker version 1.12+ to run its underlying services as docker containers. Ensure the Docker daemon is working by running docker ps and check its version by running docker --version.

To install Docker,

MacOS: Use either "Docker for Mac" or “docker-machine”. See instructions here.
Linux: Find instructions to install Docker for your Linux OS here.

ETCD

ETCD is a persistent non-sql database. TKEStack services share a running ETCD as backend.

To install ETCD,

MacOS: Install and start ETCD as a local service

brew install etcd
brew services start etcd

Linux: Run a single node etcd using docker. See instructions here.

Go

TKEStack is written in Go. See supported version here.

To install Go:

For MacOS users,
```
brew install go
```
For other users, see instructions here.

To configure go:

Make sure your $GOPATH, $GORROT and $PATH are configured correctly

Add tkestack.io to your Go env as below.

go env -w GOPRIVATE="tkestack.io"
go env -w GONOPROXY="tkestack.io"

Node.js and NPM

TKEStack requires Node.js and NPM. See here for supported versions.

For macOS users:
```
brew install nodejs
```
For other users, see instructions here.

Building TKEStack Components

TKEStack contains 11 core components, a dependency list generator and a customized installer. For detail see here.

Clone TKEStack Repository
```
git clone --depth=1 https://github.com/tkestack/tke.git
```
--depth=1 parameter is optional and will ensure a smaller download.
Build binaries

Once all the dependencies and requirements have been installed and configured, you can start compiling TKEStack on your local machine. Make sure to run it at the TKEStack root path.
```
cd tke
make build
```

After the compilation is complete, you can get all the binary executables in the _output/${host_os}/${host_arch} directory.

Create Self-signed Certificates

For security reasons, all TKEStack core components don't support insecure HTTP protocol. To enable SSL, you need to make a self-signed root certificate and a server certificate.

It is highly recommended to use the mkcert to generate certificates for developing and testing TKEStack, which simplifies the process to create certificates. See here for installation guide.

To create cert using mkcert:

cd tke
mkdir -p _debug/certificates
cd _debug/certificates
# Make a CA and install it to local trusted certificate store.
mkcert -install
# Make server certificate.
mkcert localhost 127.0.0.1 ::1

You can find your certificates at:

_debug/certificates/
├── localhost+2-key.pem
└── localhost+2.pem

0 directories, 2 files

Create Static Token

Create a static token to authenticate all TKEStack API services.

cd tke
mkdir -p _debug
touch _debug/token.csv
echo 'token,admin,1,"administrator"' > _debug/token.csv

Bootstrap TKEStack Core Components

This section will walk you through how to bootstrap TKEStack on your local machine.

TKEStack contains 11 core components. For detail see here. In order for all the services to run properly, please make sure to follow the guide below to bootstrap them in order. You could skip the optional components if it is not needed.

For your convenient,

Run the following command in the TKEStack root directory
Export ${host_os} and ${host_arch} to your environment variables according to your machine. You can find it in your tke/_output/${host_os}/${host_arch} path.
Export ${root_store} to reference the path of your root certificate created by mkcert in the previous step. For MacOS, the path is usually /Users/${username}/Library/Application Support/mkcert.

tke-auth-api

Create _debug/auth-api.json

Click to show sample config

_debug/auth-api.json

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": ["http://127.0.0.1:2379"]
  },
  "authentication": {
    "token_auth_file": "_debug/token.csv",
    "privileged_username": "admin"
  },
  "generic": {
    "external_hostname": "localhost",
    "external_port": 9451
  },
  "auth": {
    "assets_path": "./pkg/auth/web",
    "init_client_id": "client",
    "init_client_secret": "secret",
    "init_client_redirect_uris": [
      "http://localhost:9442/callback",
      "http://127.0.0.1:9442/callback",
      "https://localhost:9441/callback",
      "https://127.0.0.1:9441/callback"
    ]
  }
}

Run tke-auth-api

$ _output/${host_os}/${host_arch}/tke-auth-api -C _debug/auth-api.json

tke-auth-controller

Create _debug/auth-api-client-config.yaml

Click to view sample config

_debug/auth-api-client-config.yaml

apiVersion: v1
kind: Config
clusters:
  - name: tke
    cluster:
      certificate-authority: ${root_store}/mkcert/rootCA.pem
      server: https://127.0.0.1:9451
users:
  - name: admin
    user:
      token: token
current-context: tke
contexts:
  - context:
      cluster: tke
      user: admin
    name: tke

Create _debug/auth-controller.json

Click to view sample config

_debug/auth-controller.json

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "client": {
    "auth": {
      "api_server_client_config": "_debug/auth-api-client-config.yaml"
    }
  },
  "features":{
    "category_path": "hack/auth/category.json",
    "policy_path": "hack/auth/policy.json",
    "tenant_admin": "admin",
    "tenant_admin_secret": "secret"
    }
}

Run tke-auth-controller:

$ _output/${host_os}/${host_arch}/tke-auth-controller -C _debug/auth-controller.json

tke-platform-api

Create _debug/platform-api.json

Click to view sample config

_debug/platform-api.json

{
  "authentication": {
    "oidc": {
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    },
    "token_auth_file": "_debug/token.csv"
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": ["http://127.0.0.1:2379"]
  }
}

Run tke-platform-api

$ _output/${host_os}/${host_arch}/tke-platform-api -C _debug/platform-api.json

tke-platform-controller

Create _debug/platform-api-client-config.yaml

Click to view sample config

_debug/platform-api-client-config.yaml

apiVersion: v1
kind: Config
clusters:
  - name: tke
    cluster:
      certificate-authority: ${root_store}/mkcert/rootCA.pem
      server: https://127.0.0.1:9443
users:
  - name: admin
    user:
      token: token
current-context: tke
contexts:
  - context:
      cluster: tke
      user: admin
    name: tke

Create _debug/platform-controller.json

Click to view sample config

_debug/platform-controller.json

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "client": {
    "platform": {
      "api_server_client_config": "_debug/platform-api-client-config.yaml"
    }
  }
}

Run tke-platform-controller

$ _output/${host_os}/${host_arch}/tke-platform-controller -C _debug/platform-controller.json

tke-registry-api(Optional)

Create _debug/registry-api.json

Click to view sample config

_debug/registry-api.json

{
  "authentication": {
    "oidc": {
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "token_review_path": "/auth/authn",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    },
    "requestheader": {
      "username_headers": "X-Remote-User",
      "group_headers": "X-Remote-Groups",
      "extra_headers_prefix": "X-Remote-Extra-",
      "client_ca_file": "${root_store}/mkcert/rootCA.pem"
    },
    "token_auth_file": "_debug/token.csv"
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": [
      "http://127.0.0.1:2379"
    ]
  },
  "registry_config": "_debug/registry-config.yaml"
}

Create registry-config.yaml

Click to view sample config

registry-config.yaml

apiVersion: registry.config.tkestack.io/v1
kind: RegistryConfiguration
storage:
  fileSystem:
    rootDirectory: _debug/registry
security:
  # private key for signing registry JWT token, PKCS#1 encoded.
  tokenPrivateKeyFile: keys/private_key.pem
  tokenPublicKeyFile: keys/public.crt
  adminPassword: secret
  adminUsername: admin
  httpSecret: secret
defaultTenant: default

Run tke-registry-api

$ _output/${host_os}/${host_arch}/tke-registry-api -C _debug/registry-api.json

tke-business-api(Optional)

Create _debug/business-api.json

Click to view sample config

_debug/business-api.json

{
  "authentication": {
    "oidc": {
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    },
    "token_auth_file": "_debug/token.csv"
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": ["http://127.0.0.1:2379"]
  },
  "client": {
    "platform": {
      "api_server_client_config": "_debug/platform-api-client-config.yaml"
    }
  }
}

Run tke-business-api

$ _output/${host_os}/${host_arch}/tke-business-api -C _debug/business-api.json

tke-business-controller(Optional)

Create _debug/business-api-client-config.yaml

Click to view sample config

_debug/business-api-client-config.yaml

apiVersion: v1
kind: Config
clusters:
  - name: tke
    cluster:
      certificate-authority: ${root_store}/mkcert/rootCA.pem
      server: https://127.0.0.1:9447
users:
  - name: admin
    user:
      token: token
current-context: tke
contexts:
  - context:
      cluster: tke
      user: admin
    name: tke

Create _debug/business-controller.json

Click to view sample config

_debug/business-controller.json

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "client": {
    "platform": {
      "api_server_client_config": "_debug/platform-api-client-config.yaml"
    },
    "business": {
      "api_server_client_config": "_debug/business-api-client-config.yaml"
    }
  }
}

Run tke-business-controller

$ _output/${host_os}/${host_arch}/tke-business-controller -C _debug/business-controller.json

tke-monitor-api(Optional)

Run influxDB docker container

tke-monitor-controller requires a influxDB with database name "projects" as backend to store the monitoring data.

sudo docker volume create influxdb
sudo docker run -d -p 8086:8086  --volume=influxdb:/var/lib/influxdb  --name influxdb influxdb:latest
curl -XPOST 'http://localhost:8086/query' --data-urlencode 'q=CREATE DATABASE "projects"'

Create _debug/monitor-config.yaml

Click to view sample config

_debug/monitor-config.yaml

apiVersion: monitor.config.tkestack.io/v1
kind: MonitorConfiguration
storage:
  influxDB:
    servers:
      - address: http://localhost:8086

Create _debug/monitor-api-client-config.yaml

Click to view sample config

_debug/monitor-api-client-config.yaml

apiVersion: v1
kind: Config
clusters:
  - name: tke
    cluster:
      certificate-authority: ${root_store}/mkcert/rootCA.pem
      server: https://127.0.0.1:9455
users:
  - name: admin
    user:
      token: token
current-context: tke
contexts:
  - context:
      cluster: tke
      user: admin
    name: tke

Create _debug/monitor-api.json

Click to view sample config

_debug/monitor-api.json

{
  "authentication": {
    "oidc": {
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    },
    "token_auth_file": "_debug/token.csv"
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": ["http://127.0.0.1:2379"]
  },
  "client": {
    "platform": {
      "api_server_client_config": "_debug/platform-api-client-config.yaml"
    }
  },
  "monitor_config": "_debug/monitor-config.yaml"
}

Run tke-monitor-api

$ _output/${host_os}/${host_arch}/tke-monitor-api -C _debug/monitor-api.json

tke-monitor-controller(Optional)

Create _debug/monitor-controller.json

Click to view sample config

_debug/monitor-controller.json

Delete the business block if you didn't enable the TKE Business Service previously.

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "client": {
    "monitor": {
      "api_server_client_config": "_debug/monitor-api-client-config.yaml"
    },
    "business": {
      "api_server_client_config": "_debug/business-api-client-config.yaml"
    }
  },
  "monitor_config": "_debug/monitor-config.yaml"
}

Run tke-monitor-controller

$ _output/${host_os}/${host_arch}/tke-monitor-controller -C _debug/monitor-controller.json

tke-notify-api(Optional)

Create _debug/notify-api.json

Click to view sample config

_debug/notify-api.json

{
  "authentication": {
    "oidc": {
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    },
    "requestheader": {
      "username_headers": "X-Remote-User",
      "group_headers": "X-Remote-Groups",
      "extra_headers_prefix": "X-Remote-Extra-",
      "client_ca_file": "${root_store}/mkcert/rootCA.pem"
    },
    "token_auth_file": "_debug/token.csv"
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "etcd": {
    "servers": ["http://127.0.0.1:2379"]
  },
  "client": {
    "platform": {
      "api_server_client_config": "_debug/platform-api-client-config.yaml"
    }
  }
}

Run tke-notify-api

$ _output/${host_os}/${host_arch}/tke-notify-api -C _debug/notify-api.json

tke-notify-controller(Optional)

Create _debug/notify-api-client-config.yaml

Click to view sample config

_debug/notify-api-client-config.yaml

apiVersion: v1
kind: Config
clusters:
  - name: tke
    cluster:
      certificate-authority: ${root_store}/mkcert/rootCA.pem
      server: https://127.0.0.1:9457
users:
  - name: admin
    user:
      token: token
current-context: tke
contexts:
  - context:
      cluster: tke
      user: admin
    name: tke

Create _debug/notify-controller.json

Click to view sample config

_debug/notify-controller.json

{
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "client": {
    "notify": {
      "api_server_client_config": "_debug/notify-api-client-config.yaml"
    }
  }
}

Run tke-notify-controller

$ _output/${host_os}/${host_arch}/tke-notify-controller -C _debug/notify-controller.json

tke-gateway

Create _debug/gateway-config.yaml

Click to view sample config

_debug/gateway-config.yaml

Depending on what TKE optional services you have started, uncomment the corresponding code to allow tke-gateway to discover optional services.

apiVersion: gateway.config.tkestack.io/v1
kind: GatewayConfiguration
components:
  auth:
    address: https://127.0.0.1:9451
    passthrough:
      caFile: ${root_store}/mkcert/rootCA.pem
  platform:
    address: https://127.0.0.1:9443
    passthrough:
      caFile: ${root_store}/mkcert/rootCA.pem
  ### Optional Services ###
  # TKE Registry
  # registry:
  #   address: https://127.0.0.1:9453
  #   passthrough:
  #     caFile: ${root_store}/mkcert/rootCA.pem
  # TKE Business
  # business:
  #   address: https://127.0.0.1:9447
  #   frontProxy:
  #     caFile: ${root_store}/mkcert/rootCA.pem
  #     clientCertFile: certificates/localhost+2-client.pem
  #     clientKeyFile: certificates/localhost+2-client-key.pem
  # TKE Monitor
  # monitor:
  #   address: https://127.0.0.1:9455
  #   passthrough:
  #     caFile: ${root_store}/mkcert/rootCA.pem
  # TKE Notify
  # notify:
  #   address: https://127.0.0.1:9457
  #   passthrough:
  #         caFile: ${root_store}/mkcert/rootCA.pem

Create _debug/gateway.json

Click to view sample config

_debug/gateway.json

{
  "authentication": {
    "oidc": {
      "client_secret": "secret",
      "client_id": "client",
      "issuer_url": "https://localhost:9451/oidc",
      "ca_file": "${root_store}/mkcert/rootCA.pem",
      "username_prefix": "-",
      "username_claim": "name",
      "tenantid_claim": "federated_claims"
    }
  },
  "secure_serving": {
    "tls_cert_file": "_debug/certificates/localhost+2.pem",
    "tls_private_key_file": "_debug/certificates/localhost+2-key.pem"
  },
  "gateway_config": "_debug/gateway-config.yaml"
}

Run tke-gateway

$ _output/${host_os}/${host_arch}/tke-gateway -C _debug/gateway.json

Access TKEStack Web UI

Once all the TKEStack services are up and running, you can access TKEStack Web UI from your browser:

http://localhost:9442
https://localhost:9441

The username and password are specified in the launch configuration of the tke-auth component:

Username: admin
Password: secret

FAQ

> Question: How do I get the DEBUG log?

Answer: By default, all the core components have INFO level log. You can add the following block to your json config to enable DEBUG log.

"log": {
  "level": "debug"
}

> Question: How do I find the config options of TKEStack services?

Answer: Instead of using -C to pass the configuration file to run TKEStack services, you can simply use -h to get a full list of options.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

running-locally.md

running-locally.md

How to run TKEStack locally

Table of Contents

Prerequisites

OS Requirements

Docker

ETCD

Go

Node.js and NPM

Building TKEStack Components

Create Self-signed Certificates

Create Static Token

Bootstrap TKEStack Core Components

tke-auth-api

tke-auth-controller

tke-platform-api

tke-platform-controller

tke-registry-api(Optional)

tke-business-api(Optional)

tke-business-controller(Optional)

tke-monitor-api(Optional)

tke-monitor-controller(Optional)

tke-notify-api(Optional)

tke-notify-controller(Optional)

tke-gateway

Access TKEStack Web UI

FAQ

Files

running-locally.md

Latest commit

History

running-locally.md

File metadata and controls

How to run TKEStack locally

Table of Contents

Prerequisites

OS Requirements

Docker

ETCD

Go

Node.js and NPM

Building TKEStack Components

Create Self-signed Certificates

Create Static Token

Bootstrap TKEStack Core Components

tke-auth-api

tke-auth-controller

tke-platform-api

tke-platform-controller

tke-registry-api(Optional)

tke-business-api(Optional)

tke-business-controller(Optional)

tke-monitor-api(Optional)

tke-monitor-controller(Optional)

tke-notify-api(Optional)

tke-notify-controller(Optional)

tke-gateway

Access TKEStack Web UI

FAQ