Stacks Devnet API

Spins up a server that provides an API to deploy, delete, control, and make requests to Stacks Devnets running on Kubernetes.

Prerequisites

Running this tool requires having Kubernetes installed. Some kind configuration scripts are included in this repo. Using kind is not a requirement for using this tool, but you will need to use some tool for running local Kubernetes clusters. This is the recommended set of installation instructions for using this tool.

1. Install Kubernetes.
2. Install kubectl.
3. Install Docker Desktop.
4. Install kind.

brew install kind

5. With Docker Desktop running, create kind cluster

./scripts/kind-deploy.sh

You should now be ready to deploy this service to your local Kubernetes cluster!

Configuration

The Config.toml at the root directory of the project can be used to control some settings. This same file can be used to update both the stable and development build. The following settings are supported:

• allowed_origins - this setting is an array of strings and is used to set what origins are allowed in cross-origin requests. For example, allowed_origins = ["*"] allows any origins to make requests to this service, while allowed_origins = ["localhost:3002", "dev.platform.so"] will only allow requests from the two specified hosts.
• allowed_methods - this setting is an array of strings that sets what HTTP methods can be made to this server.
• auth_header - all requests to the API specify a network id which indicates the network that is being modified. An auth header is checked on all requests to ensure that the value of the auth header matches the id of the request. This configuration value dictates the name of that auth header
• namespace_prefix - the user's id that is used for the auth header differs slightly from the network id that is used to differentiate devnets. This value is used to determine how to mutate a user id to create a namespace. For example, if the namespace prefix is zzz-platform, and a user makes a requests with an auth header value of auth0|test-namespace, the devnet API will ensure that the request is trying to create or update a devnet with namespace zzz-platform-auth0-test-namespace.

Environment Variables

The following environment variables can be provided at runtime to further configure the API:

• KUBE_CONTEXT="<context>" stacks-devnet-api
  • With this flag, you can specify the context that will be used for all requests.
  • Default: the devnet API will deploy assets to the user's default Kubernetes context. Run kubectl config get-context to see your default.
• CONFIG_PATH="/path/to/config" stacks-devnet-api
  • Use this flag to specify the path of the Config.toml
  • Default: in development mode (building the app using cargo build), the default location is ./Config.toml; in release mode (building the app using cargo build --release), the default location is /etc/config/Config.toml

Deploying the Stable Version

In your terminal, run

./scripts/deploy-api.sh

to install the latest version of this service that has been deployed to docker (or, to quay for now). This service should now be fully running on your Kubernetes cluster. See the usage sections for steps on how to use the service.

Deploying a Development Build

Any changes made to this codebase can be tested, in part, by running cargo run. However, some features won't be available when running the service this way. Some of the inter-pod communication that takes place requires connected services to be running in Kubernetes.

To deploy a local version of this tool to you Kubernetes cluster, create a docker build and load it to your kind cluster:

docker build -t stacks-devnet-api . && kind load docker-image stacks-devnet-api

Now, modify the stacks-devnet-api.template.yaml file to deploy this new, local version rather than the latest stable version:

apiVersion: v1
kind: Pod
metadata:
  labels:
    name: stacks-devnet-api
  name: stacks-devnet-api
  namespace: devnet
spec:
  serviceAccountName: stacks-devnet-api
  containers:
  - command:
    - ./stacks-devnet-api
    name: stacks-devnet-api
-    image: quay.io/hirosystems/stacks-devnet-api:latest
-    imagePullPolicy: Always
+    image: stacks-devnet-api:latest
+    imagePullPolicy: Never

Finally, run

./scripts/redeploy-api.sh

to deploy to your local cluster.

Usage

When the service has been deployed to your Kubernetes cluster, it should be reachable at localhost:8477. The following routes are currently exposed:

• POST localhost:8477/api/v1/networks - Creates a new devnet from the configuration provided in request body. See this example object for the required parameters If any devnet assets exist when this method is used, no devnet assets will be created, and a 409 error will be returned. Note: If the namespace for this devnet has not already been created for the cluster, this will fail, unless running a development build (via cargo run). A production build expects the namespace to already exist (because the platform should have already created the namespace before creating a devnet). This devnet service should not have permissions to create a namespace. To manually create a namespace, run kubectl create namespace <namespace>
• DELETE localhost:8477/api/v1/network/<network-id> - Deletes all k8s assets deployed under the given namespace. If no devnet assets exist for the given namespace, a 404 error will be returned.
• HEAD localhost:8477/api/v1/network/<network-id> - Checks if any devnet assets exist for the given namespace. If any assets exist, this route responds with 200; if no devnet assets exist, this route responds with 404.
• GET localhost:8477/api/v1/network/<network-id> - Gets the pod and chaintip status for the specified devnet. If not all devnet assets exist for the given namespace, a 404 error will be returned. For example:

{
    "bitcoind_node_status": "Running",
    "stacks_node_status": "Running",
    "stacks_api_status": "Running",
    "bitcoind_node_started_at": "2023-07-11 00:30:02 UTC",
    "stacks_node_started_at": "2023-07-11 00:30:07 UTC",
    "stacks_api_started_at": "2023-07-11 00:30:11 UTC",
    "stacks_chain_tip": 14,
    "bitcoin_chain_tip": 116
}

• GET/POST localhost:8477/api/v1/network/<network-id>/stacks-blockchain/* - Forwards * to the underlying stacks node pod of the devnet. If not all devnet assets exist for the given namespace, a 404 error will be returned.
• GET/POST localhost:8477/api/v1/network/<network-id>/bitcoin-node/* - Forwards * to the underlying bitcoin node pod of the devnet. If not all devnet assets exist for the given namespace, a 404 error will be returned.
• GET/POST localhost:8477/api/v1/network/<network-id>/stacks-blockchain-api/* - Forwards * to the underlying stacks api pod of the devnet. If not all devnet assets exist for the given namespace, a 404 error will be returned.

Bugs and feature requests

If you encounter a bug or have a feature request, we encourage you to follow the steps below:

1. Search for existing issues: Before submitting a new issue, please search existing and closed issues to check if a similar problem or feature request has already been reported.
2. Open a new issue: If it hasn't been addressed, please open a new issue. Choose the appropriate issue template and provide as much detail as possible, including steps to reproduce the bug or a clear description of the requested feature.
3. Evaluation SLA: Our team reads and evaluates all the issues and pull requests. We are avaliable Monday to Friday and we make a best effort to respond within 7 business days.

Please do not use the issue tracker for personal support requests. You'll find help at the #support Discord channel.

Contribute

Development of this product happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving the product.

Code of Conduct

Please read our Code of conduct since we expect project participants to adhere to it.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Community

Join our community and stay connected with the latest updates and discussions:

• Join our Discord community chat to engage with other users, ask questions, and participate in discussions.

• Visit hiro.so for updates and subcribing to the mailing list.

• Follow Hiro on Twitter.