Announcing Cycle’s Internal API
We’re proud to announce the availability of the fresh, new “internal API” to our users. This API is only accessible from within a running instance on the platform.
https://docs.cycle.io/internal-api
What is it?
There are many cases where you may need to get information about how or where your instance is being run, or about changes to the environment/server this instance is running on. The internal API allows an instance of a container to make direct requests to the platform from within to find out information from that instance’s perspective, such as:
- What environment am I in?
- What server am I running on?
- How many other instances are running?
- What certificates do I have access to?
In addition, your instance can also tie into a “notification pipeline” very similar to the one accessible via public API, in order to receive streaming, real-time updates about the platform and have your instances react appropriately.
Cycle’s own service containers — load balancer, discovery, and VPN — all utilize this internal API in order to function. For example, when you deploy a new instance, the discovery service is notified via the pipeline, and uses the internal API to query the updated instances list and rebuild it’s cache. In the not-so-distant future, we intend to allow user instances to register themselves as service containers using the internal API, so if you want to use a custom DNS or load balancer service, you’ll be able to do that from within Cycle itself. More will be announced on that at a later date!
Shhh…It’s a Secret
One of the most exciting uses of the internal API will most likely be secrets management, a feature coming out very soon. Not only will you be able to securely access sensitive data over the internal API, you’ll be able to set rules and restrictions on how your instances can access those secrets. Want to ensure they can only be requested once, at startup? Or make some secrets only available to specific containers within an environment? All this, and more, will be possible in the near future.
How does it work?
Inside every container instance running on Cycle, the platform automatically mounts a Unix socket capable of receiving HTTP requests. This socket is a direct line into the platform, providing a secure channel to send and receive information.
Your instance can make requests to endpoints such as /server and receive data formatted as a JSON response (or error) nearly identical to the public API. This can be done using a shell utility such as cURL, and for convenience sake we’ve released an open source NodeJS client (written in Typescript for those who value type safety), which is available here. If you’ve used our public API client before, it should be very familiar.
Though it may be considered more of an “advanced” feature, the internal API provides a new dimension of access to your workloads, and an entirely new way to interact with the platform.
If you want to dive in and learn more, head over to our slack channel. Our community is growing, and our team hangs out there daily. Feel free to shoot us a message any time with your questions and we’ll be sure to respond!
Of course, for a more in-depth look at how to use Cycle, check out our main documentation.
Learn More + Get Started Today
Thanks for checking out our blog! If you like what you read, please subscribe.
To learn more about Cycle, please visit https://cycle.io.
To create a free account, check out our portal!
