mirror of
https://github.com/Katakate/k7.git
synced 2026-09-22 01:53:19 +00:00
G
221 lines
4.5 KiB
Plaintext
221 lines
4.5 KiB
Plaintext
---
|
||
title: "Quickstart"
|
||
description: "Install k7, prepare your node, start the API, and run your first sandbox"
|
||
---
|
||
|
||
Katakate (k7) lets you run secure, lightweight VM sandboxes backed by Kata Containers and Firecracker, orchestrated with Kubernetes. This Quickstart gets you from zero to a working sandbox via CLI and Python SDK.
|
||
|
||
<Note>
|
||
If you already installed k7 previously, consider running `make uninstall` before reinstalling to avoid stale cached files in a previous `.deb`.
|
||
</Note>
|
||
|
||
## Requirements
|
||
|
||
- Linux (amd64) host with hardware virtualization (KVM)
|
||
- Check: `ls /dev/kvm` should exist
|
||
- Cloud guidance: AWS `.metal`, GCP (enable nested virtualization), Azure D/Ev series; typical VPS often lack KVM
|
||
- One raw, unformatted disk for thin‑pool provisioning (recommended for many sandboxes)
|
||
- Docker with Compose plugin (for the API)
|
||
- Install Docker: `curl -fsSL https://get.docker.com | sh`
|
||
- Ansible for the installer (Ubuntu):
|
||
|
||
```bash
|
||
sudo add-apt-repository universe -y
|
||
sudo apt update
|
||
sudo apt install -y ansible
|
||
```
|
||
|
||
- Python 3.10+ on the client for the SDK
|
||
|
||
<Info>
|
||
Tested setup example: Hetzner Robot instance, Ubuntu 24.04 (x86_64), with an extra empty NVMe disk (for the thin‑pool). See the detailed setup guide (PDF): <a href="/tutorials/k7_hetzner_node_setup.pdf" target="_blank" rel="noopener noreferrer">k7_hetzner_node_setup.pdf</a>.
|
||
</Info>
|
||
|
||
## Install the CLI (APT)
|
||
|
||
Install the `k7` CLI on the node(s) that will host the VM sandboxes:
|
||
|
||
```bash
|
||
sudo add-apt-repository ppa:katakate.org/k7
|
||
sudo apt update
|
||
sudo apt install k7
|
||
```
|
||
|
||
## Install K7 on your node(s)
|
||
|
||
This installs and wires up Kubernetes (K3s), Kata, Firecracker, Jailer, and the devmapper snapshotter with thin‑pool provisioning:
|
||
|
||
```bash
|
||
k7 install
|
||
```
|
||
|
||
|
||
|
||
<Check>
|
||
You should see "Installation completed successfully!" when done. Add `-v` for verbose output.
|
||
</Check>
|
||
|
||
## Start the API and manage keys
|
||
|
||
### Start the API
|
||
|
||
```bash
|
||
k7 start-api
|
||
```
|
||
|
||
|
||
|
||
### Check API status
|
||
|
||
```bash
|
||
k7 api-status
|
||
```
|
||
|
||
|
||
|
||
### Get the public endpoint
|
||
|
||
```bash
|
||
k7 get-api-endpoint
|
||
```
|
||
|
||
|
||
|
||
### Generate an API key
|
||
|
||
```bash
|
||
k7 generate-api-key mykey
|
||
```
|
||
|
||
|
||
|
||
### Stop the API
|
||
|
||
```bash
|
||
k7 stop-api
|
||
```
|
||
|
||
|
||
|
||
<Info>
|
||
- Ensure your user is in the `docker` group to manage the API containers.
|
||
- API keys are stored at `/etc/k7/api_keys.json` by default. Authentication accepts `X-API-Key` header or `Authorization: Bearer <token>`.
|
||
</Info>
|
||
|
||
## Create your first sandbox via CLI
|
||
|
||
Example `k7.yaml`:
|
||
|
||
```yaml
|
||
name: demo
|
||
image: alpine:3.20
|
||
namespace: default
|
||
env_file: /root/secrets.env
|
||
limits:
|
||
cpu: "100m"
|
||
memory: "128Mi"
|
||
before_script: |
|
||
# Installing curl. Egress open during before_script, then restricted (empty whitelist) afterwards
|
||
apk add curl
|
||
echo $ENV_VAR_1
|
||
egress_whitelist: []
|
||
```
|
||
|
||
### Create a sandbox
|
||
|
||
```bash
|
||
# Uses k7.yaml in the current directory by default
|
||
k7 create
|
||
```
|
||
|
||
|
||
|
||
### Shell into your sandbox
|
||
|
||
```bash
|
||
k7 shell demo
|
||
```
|
||
|
||
|
||
|
||
### List sandboxes
|
||
|
||
```bash
|
||
k7 list
|
||
```
|
||
|
||
|
||
|
||
### Delete a sandbox
|
||
|
||
```bash
|
||
k7 delete my-sandbox-123
|
||
```
|
||
|
||
### Delete all sandboxes
|
||
|
||
```bash
|
||
k7 delete-all
|
||
```
|
||
|
||
### Prerequisites for the SDK
|
||
|
||
```bash
|
||
# Ensure the API is running and you have an endpoint and API key
|
||
k7 start-api
|
||
k7 get-api-endpoint
|
||
k7 generate-api-key my-key
|
||
```
|
||
|
||
## Create your first sandbox via Python SDK
|
||
|
||
Install the SDK on your client machine:
|
||
|
||
```bash
|
||
pip install katakate
|
||
```
|
||
|
||
Use the synchronous client:
|
||
|
||
```python
|
||
from katakate import Client
|
||
|
||
k7 = Client(endpoint="https://<your-endpoint>", api_key="<your-key>")
|
||
|
||
# Create sandbox
|
||
sb = k7.create({
|
||
"name": "my-sandbox",
|
||
"image": "alpine:latest"
|
||
})
|
||
|
||
# Execute code
|
||
result = sb.exec('echo "Hello World"')
|
||
print(result["stdout"]) # or just print(sb.exec("echo hi"))
|
||
|
||
# List and cleanup
|
||
print(k7.list())
|
||
sb.delete()
|
||
```
|
||
|
||
Async variant:
|
||
|
||
```python
|
||
import asyncio
|
||
from katakate import AsyncClient
|
||
|
||
async def main():
|
||
k7 = AsyncClient(endpoint="https://<your-endpoint>", api_key="<your-key>")
|
||
print(await k7.list())
|
||
await k7.aclose()
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
## Next steps
|
||
|
||
- Explore the CLI guide: `/guides/cli`
|
||
- Explore the Python SDK guide: `/guides/python-sdk`
|
||
- Integrate with the REST API: `/api/introduction`
|
||
|
||
|