Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 46 additions & 10 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
# See the License for the specific language governing permissions and
# limitations under the License.

GOOGLE_CLOUD_PROJECT ?= $(shell gcloud config get-value project 2>/dev/null)
ATE_ENV_IMAGE_REPO ?= gcr.io/$(GOOGLE_CLOUD_PROJECT)
ATE_ENV_IMAGE_REPO ?= localhost:5001/ate-env
SNAPSHOTS_BUCKET ?=

# Baked into the ate-env CLI by build-cli (release.yaml does the same with the
# published digests): `ate-env --version`, and the defaults of manifest
Expand All @@ -23,7 +23,7 @@ ATE_ENV_API_IMAGE ?=
ATE_ENV_GUEST_IMAGE ?=
CLI_LDFLAGS := -X main.version=$(VERSION) -X main.defaultAPIImage=$(ATE_ENV_API_IMAGE) -X main.defaultGuestImage=$(ATE_ENV_GUEST_IMAGE)

.PHONY: build build-cli install test vet clean images python-protos python-test verify-boilerplate verify-gofmt
.PHONY: build build-cli build-install install-access install test vet clean images python-protos python-test verify-boilerplate verify-gofmt

build:
go build ./...
Expand All @@ -33,6 +33,40 @@ build:
build-cli:
go build -trimpath -ldflags "$(CLI_LDFLAGS)" -o bin/ate-env ./cmd/ate-env

# Install into the current kubectl context; Substrate must already be running.
build-install:
@test -n "$(SNAPSHOTS_BUCKET)" || { echo "SNAPSHOTS_BUCKET is required (e.g. gs://bucket/prefix/)" >&2; exit 1; }
@command -v ko >/dev/null && command -v kubectl >/dev/null && command -v kubectl-ate >/dev/null && command -v jq >/dev/null
$(MAKE) install-access
$(MAKE) build-cli images
./bin/ate-env manifest \
--api-image "$$(cat bin/ate-env-api.image)" \
--worker-image "$$(cat bin/ateworker-gvisor.image)" > bin/deployment.yaml
./bin/ate-env manifest template \
--guest-image "$$(cat bin/ate-env-guest.image)" \
--snapshots-bucket "$(SNAPSHOTS_BUCKET)" > bin/template.yaml
kubectl apply -f bin/deployment.yaml
kubectl -n ate-env rollout status deployment/ate-env-api --timeout=300s
kubectl-ate create actor-template -f bin/template.yaml

# kubectl-ate must run as an administrator; the API itself only gets editor.
install-access:
@command -v kubectl-ate >/dev/null && command -v jq >/dev/null
@mkdir -p bin
kubectl-ate get atespaces -o json > bin/atespaces.json
@set -eu; \
exists=$$(jq -r 'any(.atespaces[]?; .metadata.name == "ate-env")' bin/atespaces.json); \
if test "$$exists" = false; then \
kubectl-ate create atespace ate-env; \
fi
@set -eu; \
policy=$$(kubectl-ate get access-policy -a ate-env -o json); \
if test -n "$$policy"; then action=update; else action=create; policy='{}'; fi; \
printf '%s\n' "$$policy" | jq --arg member 'user:system:serviceaccount:ate-env:default' \
'.bindings = ((.bindings // []) | if any(.[]; (.role == "editor" or .role == "owner") and any(.members[]?; . == $$member)) then . elif any(.[]; .role == "editor") then map(if .role == "editor" then .members = ((.members // []) + [$$member]) else . end) else . + [{role: "editor", members: [$$member]}] end)' \
> bin/access-policy.json; \
kubectl-ate "$$action" access-policy -a ate-env -f bin/access-policy.json

# Install ate-env and ate-env-api to $GOBIN (or $GOPATH/bin).
install:
go install ./cmd/...
Expand Down Expand Up @@ -69,15 +103,17 @@ SUBSTRATE_VERSION = $(shell go list -m -f '{{.Version}}' go.ate.dev/substrate)

images:
@echo "Building and pushing container images to $(ATE_ENV_IMAGE_REPO)..."
@guest_img=$$(KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO)/ate-env-guest ko build --bare ./cmd/ate-env-guest | tail -n 1); \
api_img=$$(KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO)/ate-env-api ko build --bare ./cmd/ate-env-api | tail -n 1); \
worker_img=$$(cd $(SUBSTRATE_DIR) && KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO) \
@mkdir -p bin
@set -eu; \
KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO)/ate-env-guest ko build --bare ./cmd/ate-env-guest > bin/ate-env-guest.image; \
KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO)/ate-env-api ko build --bare ./cmd/ate-env-api > bin/ate-env-api.image; \
(cd "$(SUBSTRATE_DIR)" && KO_DOCKER_REPO=$(ATE_ENV_IMAGE_REPO) \
GOFLAGS=-ldflags=-X=go.ate.dev/substrate/internal/version.Version=$(SUBSTRATE_VERSION) \
ko build --base-import-paths ./cmd/ateworker-gvisor | tail -n 1); \
ko build --base-import-paths ./cmd/ateworker-gvisor) > bin/ateworker-gvisor.image; \
echo "Published:" && \
echo " --guest-image $$guest_img" && \
echo " --api-image $$api_img" && \
echo " --worker-image $$worker_img"
echo " --guest-image $$(cat bin/ate-env-guest.image)" && \
echo " --api-image $$(cat bin/ate-env-api.image)" && \
echo " --worker-image $$(cat bin/ateworker-gvisor.image)"

clean:
rm -rf bin
44 changes: 37 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,25 @@ go install github.com/agent-substrate/env/cmd/ate-env@latest
## Quickstart

Prerequisites: a cluster running [Agent Substrate](https://github.com/agent-substrate/substrate)
at or after [`63a17a92`](https://github.com/agent-substrate/substrate/commit/63a17a92), and a GCS
bucket for snapshots. ate-env is built and tested against
[`3a2ca623`](https://github.com/agent-substrate/substrate/commit/3a2ca623).

### Substrate Setup for Local Kind

From Substrate, create the cluster if needed and install
Substrate with both the CLI proxy and ate-env-api identities allowed:

```bash
# Only needed when creating a new cluster.
hack/create-kind-cluster.sh

go run ./cmd/ate-setup deploy ate-system --kind \
--credential-provider='{"name":"k8s.io"}' \
--preview=PerTemplateSnapshotLocation \
--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client,spiffe://cluster.local/ns/ate-env/sa/default
```

The ingress allowlist includes the CLI proxy and ate-env-api's default pod
identity. Retain both, plus any other clients, on subsequent Substrate deployments.
The preview flag enables per-template snapshot locations for the template below.

### 1. Build and Push the Images

Expand All @@ -66,14 +82,28 @@ build it from that Substrate checkout with `ate-setup publish worker-images` ins

### 2. Deploy the Kubernetes Resources

Deploy the namespace, worker pool, and API service:
First, using a Substrate administrator identity, create the atespace and grant
the API service account access. For a new installation:

```bash
kubectl-ate create atespace ate-env
kubectl-ate create access-policy -a ate-env -f - <<'EOF'
bindings:
- role: editor
members:
- user:system:serviceaccount:ate-env:default
EOF
```

Then deploy the namespace, worker pool, and API service using the printed image
digests:

```bash
ate-env manifest \
--api-image $ATE_ENV_IMAGE_REPO/ate-env-api@sha256:<digest> \
--worker-image $ATE_ENV_IMAGE_REPO/ateworker-gvisor@sha256:<digest> | kubectl apply -f -

# Ensure that the pods are running:
kubectl get pods -n ate-env
kubectl -n ate-env rollout status deployment/ate-env-api
```

### 3. Register the ActorTemplate in Substrate
Expand Down Expand Up @@ -286,4 +316,4 @@ For complete runnable Go programs:
# Delete the ate-env namespace to remove all components:
kubectl delete ns ate-env
kubectl ate delete actor-template --atespace ate-env default-template
```
```
2 changes: 1 addition & 1 deletion cmd/ate-env/manifest.go
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ binaries default it to the ate-env-guest image published with the release
(see docs/release.md), or build and push your own with make images`)
}
if c.snapshotsBucket == "" {
return errors.New("--snapshots-bucket is required; use an object-storage bucket (e.g. gs://bucket/prefix/)")
return errors.New("--snapshots-bucket is required")
}
if c.rootfsImage != "" {
if _, err := apiservice.ImageDigest(c.rootfsImage); err != nil {
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ require (
github.com/google/uuid v1.6.0
github.com/modelcontextprotocol/go-sdk v1.8.0
github.com/spf13/cobra v1.10.2
go.ate.dev/substrate v0.6.1-0.20261030223608-6ddb1934dd75
go.ate.dev/substrate v1.0.0
google.golang.org/grpc v1.84.0
google.golang.org/protobuf v1.36.12
k8s.io/api v0.37.0
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
go.ate.dev/substrate v0.6.1-0.20261030223608-6ddb1934dd75 h1:tzl0PWr3PrzAts2HrKztaMK6q3xaDmzwQARl3JI80xU=
go.ate.dev/substrate v0.6.1-0.20261030223608-6ddb1934dd75/go.mod h1:sS0tm65aYf+xIkkl7mTSQAS2P8tXM5xUOTnLXIE4tvc=
go.ate.dev/substrate v1.0.0 h1:7zFdRCb4e4OHoJUUWugBCQ7m1GLHHb1SxJo05HqEDjw=
go.ate.dev/substrate v1.0.0/go.mod h1:iBSRX82TClE5CSsD80HoYsxVP81NSpf0zKKTW+2s/+0=
go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
Expand Down