From Git to Governed Execution: Run Scripts, Playbooks & Agent Tools with Itential Gateway

Joksan Flores • 00:01

Hi, everybody. My name is Joksan Flores. I am a principal solutions engineer here at Itinchil, and today I will be doing an Itential Gateway demo. And more than we’ve done some of these demos before, but this is actually the idea is to refresh on the capabilities of the gateway and kind of focus on some of the newer functionality and newer ways of management and things like that. So, we’re going to be doing a little bit of PowerPoint, a little bit of CLI, a little bit of GUI, and we’re going to even do some AI agent stuff. What is the Itential Gateway? The Itential Gateway is a governed execution gateway that runs as part of the Itential Platform stack.

Joksan Flores • 00:43

And the idea of the gateway is that it serves as the execution engine for assets such as your Python scripts, Ansible playbooks, OpenTelfo plans, and even executables like shell scripts and so on that are deployed in your own infrastructure next to your infrastructure, right? Deployed in your environment. The gateway is always deployed remotely inside the customer environment and it communicates with the Itential platform in a secure fashion using mutual TLS with no requirements for VPN. And the idea of the gateway is everything that gets deployed in the gateway is an ephemeral asset. What does that mean? What that means is that the gateway connects directly to Git and it pulls automations that are existing in the environment as they get configured. And we’re going to be showing that in a little bit.

Joksan Flores • 01:33

Directly from the repository. That way they don’t have to be copied. There’s no need to maintain multiple copies of the same script, and so on. You only commit to your Git repo, and they get executed directly from the repo along with the dependencies inside of the gateway and as part of the platform. Every execution of these assets inside of the gateway is a clean, isolated environment. It gets injected at runtime, especially things like secrets, requirement, dependencies, and so on. Everything as laid out on the repo or the service declaration is what specifies how that service, that particular script or asset gets executed.

Joksan Flores • 02:16

So if I declare that the asset comes from the development branch or from the main branch, that it has a requirement of a specific Nameco library, that it needs a particular secret injected at runtime, and so on. All that happens during runtime. The platform has no awareness of it, and there’s no state saved inside of the gateway itself. There’s a full audit trail represented of what it’s done without obviously spelling out secrets in the audit trail, but everything is logged, but at the same time, all ephemeral, like I was saying before. The services themselves are governed and exposed by the gateway. They become callable via workflows, via APIs, and via also agents inside of the platform. So every service that gets created in the gateway itself gets exposed to the platform and it becomes a callable tool inside of the workflow engine of the platform, which we will demonstrate inside of our AI agents as tools.

Joksan Flores • 03:14

And it also gets its own API. How does it work? And I kind of talked about this a little bit. The idea here is that when a service gets added inside of the gateway and it gets called for execution, and we will see some of those during the demo portion of it, the code or the repo itself gets pulled from Git directly. The gateway will need access to Git. It could be an internal or external Git, right? And it gets pulled real time.

Joksan Flores • 03:42

A new clean environment gets built inside of the gateway. The gateway itself will build the runtime environment for that specific asset. In the case of a Python script, it’ll look for requirements.txt file or a pyproject.toml. For Ansible, it’ll look for requirements.yaml and so on, right? Same thing for OpenTOFU. The services themselves will have a secrets declaration when needed. So, if you need to inject a password as an environment variable into a service, it gets declared when the service gets created.

Joksan Flores • 04:15

That secret could come locally from the gateway or it could come from a secrets manager, but it only gets injected at runtime, meaning the gateway itself, unless specified, it’s not holding any secrets. And then the execution happens in an isolated fashion, right? Every execution is new. When it gets called, it’s isolated from other executions, and then it gets exposed either via standard out on the CLI, which we will test here today. It also gets exposed to the workflow engine as the execution standard out for that specific asset. And also, when we call them via agents, it gets exposed to the agents as tool results. And then the environments get destroyed, and we get some locks, right?

Joksan Flores • 05:00

The gateway will lock to the journal of the system. The environment itself gets destroyed, and nothing is left behind. And every single execution starts clean. So now let’s get into the demo. And like I specified before, we’re going to do a little bit of CLI and we’re going to do some GUI things and so on. So let’s just open another window here on the side. Okay, so I have an a Okay, so I have a script that I have created here that I have readily available that I could use for this and this will serve as the example that we are going to use.

Joksan Flores • 05:54

This is a very simple script. It has no requirement dependencies in this case, but it could have a requirements that texting here inside of the repo itself. But it has, and what it does is it actually serves as a way to pull the internet routes from a route server in this case i’m pointing to one of the comcast route servers and this is what the script will look like one of the things that you will notice in here is that it’ll have its own imports and everything else the script is rather lengthy it has a hard-coded username but one of the things that will that we’ll key on later is the password itself is passed in as an environment variable when you look at it here and we will use this because this will be a way of kind of understanding and explaining how the one of the gateways most important features work which is secret injection so that you don’t have to leave any of your secrets inside of your report or anything else in this case I’m leaving my username this is not something you would do normally you would configure it as a variable or you would pass it in as a secret as well but we will show that in a 2nd So I have my repository. My repository itself has the Python script. It could have any other files like requirements.txt and so on. In this case, I don’t have any dependencies.

Joksan Flores • 07:06

And then I also have a decorator, which we will use as well for my service declaration. Let’s get down to the CLI, to the gateway, and we’re going to show how we add new services into this gateway and how they show up inside of the platform. So, I have a gateway that is pre-configured. It’s running on my laptop, but it’s empty. So, when I do an IGCTL get services, it’ll show empty. Everything is empty here. And we’re going to do a couple of things.

Joksan Flores • 07:31

We’re going to add services manually via CLI, and then we’re going to clean them all up and we’re going to re-import them. Because what we’re going to show here is the kind of the advanced way of how you would do it when you’re developing in your environment. But as you go on and as you manage gateways via pipeline, and as you add assets and scale, 10, 20, 30, 40 scripts, 40 assets, and so on, you want to manage those in a more scalable way. And we actually have a file that we will use that I’ll show you in a 2nd as well. So, what we’re going to use, the 1st thing that we’re going to do is we’re going to instantiate the repository. So, let’s show that repositories are empty. So, we’re going to do GCTL create repository.

Joksan Flores • 08:13

I’m going to call it all the same for the sake of standardizing. I’m going to call it internet routes. And I’m going to declare the URL right here. And I have it on my clipboard. And that points to my HTTPS URL of my GitHub repo. Notice that as I go along here, there’s a lot of things that I can set. I can set reference, which sets to, it could be a reference to a tag, to a particular build of that asset, or it could also be a branch.

Joksan Flores • 08:40

In this case, I’m going to default to main, but it could be a development branch or a branch of a specific name. So I got a lot of that capability. And then I can also pass other things like private keys and so on. So if I have an RSA and whatnot, and I can do tag-based filtering. Next, we’re going to go and create the decorator internet routes. And then I’m going to do schema. And I’m going to pass my schema from that repo.

Joksan Flores • 09:09

And I’m going to actually have it here already. It’s the same schema. It’s encased by single quotes and it doesn’t have any choices. That’s it. So this is a JSON. This schema itself could come from a file. I wanted to make sure that I did it all here so that I could show it all step by step.

Joksan Flores • 09:25

So once I do that, it gets parsed and it gets added here. What this decorator does is it actually tells the gateway what are the parameters that are needed in order to run this script. This script takes a single argument. It’s called numRoutes. So if you were to run this script via CLI, say Python via virtual environment or what have you, you would do Python3 space internet routes.py dash-numRoutes space 100. That’s what this does, right? It tells the gate, hey, these are the parameters, that’s how they need it, and blah, blah, blah, blah, right?

Joksan Flores • 09:55

All those kind of attributes. And then we’re gonna do, we’re also gonna add a secret. So, for adding a secret, and this for that password that I was kind of shown before, we need to pass in that password as a, and I wanted to have it as a secret because I don’t want to pass it in verbatim. I don’t want to have, I don’t want to have it on my repo. So, I’m going to do, I’m going to create it. In this case, I’m going to create a local secret in the gateway: secret R server pass value R views XR. This is a password of the internet router or the internet.

Joksan Flores • 10:33

Route server, and then I’m gonna do encryption, but I’m gonna pass an encryption file. So, this will be the encryption file that will be used to encrypt this password. It’ll be encrypted in the database. This is a the encryption key itself needs to be both in the client, which is what I’m gonna use now to encrypt it one way. And then, also, this file is also configured in the server side of the gateway as well as a decryption file, the decryption key. This is an RSA, just like you would, or a PEM file, just like you would use for things like SSH. So, this file needs to be on both sides in order to decrypt it.

Joksan Flores • 11:09

But so, we have a mechanism of out-of-the-box encrypting your passwords and passing in a secure way to the services. Or you could, like I said, you could also point to Secrets Manager. And then, I’m going to do my service creation. So, we’re going to do the service creation by pieces here. I’m not going to type the whole thing, so we’re just going to paste by hand. So, IGCTL create service Python script internet routes. We’re going to point it to the repository.

Joksan Flores • 11:36

Repository internet routes, which corresponds to this repo that we created up here. So, it has to correspond to this name. The file name, which is the Python script file name as it came from the repo itself, the decorator. Now, we standardize everything, so for us, it’s easy. Decorator internet routes and the secret. Reference. Now, this secret reference is also important here.

Joksan Flores • 12:00

In my case, I have everything. It’s going to be, I’m going to be using the same variable name, but you can actually map here the name of the secret, which is what the name that corresponds that’s on the gateway, and type environment because it’ll be passed as an environment variable, and the target. So, this will be what the script of the variable that the variable name that the script will look for. And it’s the same in here, our server pass. So, if it was something different, you would create something different there. And I have a typo. Let’s see, where is it at?

Joksan Flores • 12:30

Create service. Oh, I know where it is. Let’s fix that. Okay, so now that we created our service, we can see all its attributes here and how it’s kind of pointing to all the other things that we refer to. So we have a service, it’s of name internet routes, the repo points to internet routes as well. File name is internet routes.py, that creator, blah, blah, blah, and all these assets. Now, a common question that we get from customers a lot of times is: can the repo have multiple assets in it?

Joksan Flores • 13:24

And the answer is yes. As long as the dependencies are shared, the answer is yes. Also, you can do, you can have multiple working directories inside of the same repo. So if I had a directory inside that corresponded to one directory per script with its own requirements, that text file, and so on, I could also do that. So multiple ways of kind of supporting different deployment mechanisms. And we’re trying to make it super flexible for our customers to deploy. And now I’m going to actually go and test this service.

Joksan Flores • 13:54

So let’s go ahead and run it locally 1st . Now, this is not something, this is not the most common way of use of the gateway. Most customers will use this attached to an Itentialal platform. But in this case, we have the ability to test our services locally as well. So I tested my service. It runs just fine. We get the start time and time and some of the telemetry from it.

Joksan Flores • 14:15

But then we get the standard out of the whole script. The script is just going to print standard out. If I want to print some structured data, I could. And then also, I can run this with a verbose flag that will tell me everything that’s going on. So I’m communicating with my gateway server, which is hosted locally in my laptop here. And it’s actually going and executing, you know, some of that stuff, right? Pulling the repo down, building the dependencies, and so on when necessary, and showing the standard out here.

Joksan Flores • 14:47

Okay, so now that we have that, I’m going to go ahead and actually delete everything because I want to show a new way of adding all these assets at scale. And this is what I’m going to show we’ll be able to use for our pipelines and so on, or via API if we wanted to deploy multiple services at once. So let’s do at GCTL get services. Repositories. All right, you get the idea. My gateway is entirely clean. So now let’s go back to the Itential platform and we’re going to go to our gateway manager.

Joksan Flores • 15:28

And I am going to zoom in. I think you zoom in. Yep, this is perfect. So we’re in our gateway manager and I have loads and loads and loads of gateways here. There’s loads of gateways that we use for different types of testing, different deployments, and so on. In this case, I’m going to focus on this one, which is the cluster that I’m using. It’s called Cluster Nerd because I’m a nerd.

Joksan Flores • 15:49

And this is what the gateway has in it. If I go to it, it has a linked certificate. There’s loads of certificates. Like I said and talked about before during the slides, the gateway will have a mutual TLS relationship with the platform. So there’s no VPN required. The gateway itself, from my laptop, and this platform is actually hosted in our cloud. The gateway itself will reach out.

Joksan Flores • 16:12

To that URL. And that URL could be an internal IP address or it could be an external URL that’s resolved via public DNS and so on. In this case, this is public DNS from my laptop. The gateway, it’s reaching out to the platform and authenticating itself with some self-signed mutual TLS certs that have added on both sides. I can have, you know, fully on certificates signed by CA and so on. We all, you know, we can go to the details of mutual TLS later. But essentially, it’s a protected relationship and all the traffic is encrypted and so on.

Joksan Flores • 16:42

And there’s no requirement for VPN from the customer’s premise, and the gateway still remains deployed locally. So I have my cluster here, my gateway, my certificate is assigned to it. And when I go to services, I only see the pre-created services that are used for talking to network devices, which these are kind of brokered and they come with the gateway by default, right? These are out of the box. But once I go and add new services, they’ll all show up in here. So let’s go ahead and do that. So I have a pre-created file, and in here, we can go into the cluster itself.

Joksan Flores • 17:14

We can go and say import configuration, and I can upload a file. So what I’m going to do is I’m going to go find that file that I have, and I’m going to drag and drop it here. And it’s called interroutes.yaml. And I can share. Let me see if it opened the browser as well. Let’s see, will it open here? Nope, it will not.

Joksan Flores • 17:47

This is what the file looks like that I’m going to add into the gateway. So, basically, very similar to what we just did via CLI, only that this is a YAML file at the moment. And it has everything that we added. It has that decorator with the number routes parameter. It’s got the repository with the URL pointer. It’s got the service declaration saying, hey, this is a Python script. The file name is internetroutes.py.

Joksan Flores • 18:10

It has an empty working directory, it ties it into the repository, and it’s got the decorator. And it also noticed it has a secret as well, but encrypted entirely. So this file will declare the entirety of that service that we just had along with all its references. Obviously, the secreting here is for my local secrets only. If I had a secret reference into a secrets manager, then that wouldn’t be here. And obviously, that’s probably the way that we recommend that our customers deploy. So let’s go back into our gateway manager and upload that file.

Joksan Flores • 18:49

And we will paste the cluster ID here. I also have a flag here to force. So if I wanted to replace it, I obviously cleaned up my gateway before. I deleted all my assets after I recreated them with the CLI. But I could also overwrite everything if I wanted to using this force flag. So I’m going to import an overwrite. And once I do that, I can click into my gateway again and go to services.

Joksan Flores • 19:12

And now, let’s refresh this. There we go. And now I have my internet route services added, my service added. And it’s identified here as a type Python script. And it’s got the argument decorator here, number routes, 100. That’s kind of how it gets called. So now my gateway manager asset has an endpoint here that I can use to execute.

Joksan Flores • 19:39

And once I go and look into the rest of the platform, this will show up as a service everywhere. Let’s look at how we add that service itself that we just added into the gateway into a workflow. So let’s do gateway demo internet routes. So I’m going to create a new workflow, brand new, and what I’m going to do is I just need the run service task. And we’re going to zoom in in a 2nd . Zoom in. And I’m also going to drag and drop my view data task so that we can see the output itself.

Joksan Flores • 20:17

And I’m going to plug that in there. Okay, so let’s zoom in in here. Let’s close the task canvas. And once I add my service into the gateway, the gateway itself will show up in here. All the assets are immediately brokered into the platform. So if I go here into my drop-down and I have a filter here, right? Ansible Python, OpenTOFO executable, like I said before, my gateway is extremely clean.

Joksan Flores • 20:42

It only has this one asset. But if I were to look at other gateways, like our lab gateway, there’s lots of stuff in here: Python scripts, Ansible playbooks, and so on. There’s all sorts of things, right? If I went to filter by Python, there’s OpenTOFO plans, executables for getting the time, and lots and lots and lots of stuff. So I’m going back to my service. It’s called internet routes.

Joksan Flores • 21:04

And if you look at what the decorator also gives us is the capability of now the platform understands the parameters that need to get passed to the script. So this case it has a here, number of routes, and it has number of BGP routes to retrieve. This comes straight up for that decorator recreated before. So this gives us the ability to now specify here. And from the canvas perspective, now all the builders have the ability to know, okay, what does the script do? It has a description for it and so on, and it has every single argument. And I can have that argument be passed in as a job, as a task variable, or as a static value.

Joksan Flores • 21:41

So in this case, I’m going to pass it as a static value. I’m going to do 50 routes. Let’s do that for now. And we configured that, and then also let’s configure my view data. Internet routes is going to be my header, and this is what we’re going to be able to see. What is it? Show IP route output.

Joksan Flores • 22:07

Let’s just do show IP route output. And then the body is going to be the task, which is called run a gateway service. And with this case, we can rename it, say run internet routes. Go back. It says run internet routes now. My task variable is the result. And then I’m going to go ahead and actually query this out because we get an optic back from this.

Joksan Flores • 22:37

And that all looks good. That result that I CD out. So let’s go ahead and run this. And now my service is running. So if I were to go to my gateway, I will see the logs of everything that’s going on, just the same thing that we did in our CLI. It’s actually going to clone the repo. It’s going to fetch to Git.

Joksan Flores • 23:00

It’ll clone the whole repo to the gateway locally. It’ll build an environment if it needs to based on the requirements, that text, and so on. And it’ll execute the script with the parameters I passed in, namely that 50, that numRouts 50 that I passed in. And if I go to my work center, I can see my output here. And I can see, okay, show IP route output. And these are the 50 routes or so, right? It’s kind of some, it’ll summarize.

Joksan Flores • 23:26

That script will do some summarization or something like that. So let’s go ahead and do success here. So we’ve demonstrated so far that we can add a service, it’ll broker it to the platform, it’ll show up in our gateway manager as an endpoint there for execution. I can call it from a workflow. But also, one of the other peculiar things that we do and one of the themes throughout the whole platform is we’re able to actually expose these scripts as agent tools. So I’m going to go ahead and go into my agent builder here. And I have a gateway demo project already created.

Joksan Flores • 24:00

And I’m going to go ahead and create a new agent. And let’s call it internet routes agent. I already did some of this for practice earlier. So I’m going to call it internet routes agent. And I’m going to say use the internet routes tool to fetch 20 internet routes. You know, if I can type internet routes and summarize them in a clean table. Okay, so that seems like a very, very, very simple prompt.

Joksan Flores • 24:33

Obviously, this is not much of a very useful agent, but at least this gives us the idea of what the things that we could do. I can use this as one of the steps, or I can use services as one of the steps in my agents. Let’s go back down here. And now in the tools section, we have loads of tools in the Itential platform, API calls, workflows, and so on. So in this case, I’m just going to go and look for internet routes. And you can see here that it shows up. Internet routes, it’s a tool-type gateway service.

Joksan Flores • 25:02

It’s a source cluster nerd. And I can do other things like overriding the decorator and so on, but I don’t want to do any of that right now. And I have my, I’m going to select my profile and model down here. So let’s go and change that and change it to Sonnet 5. And I can add permissions as well to it. And let’s go and run that agent. Notice I didn’t add any human in the loop to any human in the loop tools or anything like that.

Joksan Flores • 25:28

I just wanted to keep it super simple. But now you can see that my agent’s running. My prompt is saying use the internet routes just like we specified it. The agent reasoned through it. I’ll fetch the 20 internet routes. And if we go back here, my agent is able to successfully use this script as a tool. And all those assets we also expose northbound of the platform as well as API callable.

Joksan Flores • 25:53

So multiple ways of kind of brokering those assets from the gateway. Like I said, remotely, we can have multiple these clusters deployed in different ways. They can all have common assets. They can have individual assets. The gateway can be used to talk to network devices and so on. But yeah, you can kind of see here how we’re using it as an agent tool. So the tool call happened here.

Joksan Flores • 26:16

Here are the inputs and the outputs. So we see the whole standard out of everything that went on. And now we have the agent summary. So here’s a summary of the BGP internet routes. And of course, it starts at the 1.0 and it’s got NexOps and all those kinds of things. So yeah, the gateway service is entirely usable as an agent tool, as a workflow tool, as an individual tool itself. And this applies for every single type of service:

Joksan Flores • 26:39

Python, Ansible, OpenTofu, or executable services. So, now that we did that demo, let’s talk about what makes the gateway different. I think one of the biggest things for me and that makes it very interesting and helps a lot of our customers kind of fulfill the requirements is the fact that the gateway is entirely ephemeral, right? It only stores the operational states during the runtime of the asset, right? Your script logic itself, everything, the latest changes of the script and all those things live inside of the repo. So, you can make changes at any time, have references, have an entirely GitOps-based experience where your gateway is only fetching from the main branch of the repository, but you have development ongoing. And as you promote code, it gets deployed into your environment for your workflows to access, your agents to access, or even as standalone calls.

Joksan Flores • 27:41

This is a very much GitOps-based architecture. If you notice from the beginning, when I created the gateway services, uploading the YAML file to the platform, there was also a way of pointing to a Git repo. So that file itself could live in a repo, and I can make sure that my gateway always takes up to date. The configuration DSL describes every resource inside of it, and the gateway itself is just the execution engine. I can deploy that file over and over in a daily fashion. It could be pipeline-driven, it could be schedule-driven, and that does not incur into a rebuild. It’s just a mere traditional way of deploying things inside of the gateway.

Joksan Flores • 28:26

The gateway itself does not have a web UI, and that is on purpose. The web UI normally represents an attack surface, more things to patch, more things to keep up with it. We purposefully don’t have a web UI, and that makes the gateway be a lean executable. It runs itself, it’s less than 100-meg executable. It can live in a very small or a very large deployment. You choose depending on your needs, and the gateway itself can just run as a headless application as part of the platform called via workflows or agents. And it’s entirely visible and dependent on the gateway manager relationship.

Joksan Flores • 29:05

Gateway manager will manage that connection. One of the biggest things, and especially nowadays for a lot of our customers, and especially in some of the sectors like energy and finance and so on, that need a lot of security and at the same time want to have that connectivity back to our cloud platform is mutual TLS, the use of mutual TLS. We don’t need any VPN tunnels for this gateway to run. As long as mutual TLS is allowed and established using trusted certificates, the gateway can talk to the platform and back, and the gateway could live anywhere. It could live on-premise. In this case, you can see it’s running on my laptop for the sake of demo purposes, but it could live on the premise in the established server in a data center. It could live in the cloud in your AWS VPC or your Azure VNet and so on.

Joksan Flores • 29:58

It could live anywhere. And that’s where a lot of our customers deploy, depending on the needs. Some cloud teams deploy in AWS and some network teams deploy on-premise. So it fits the user’s needs and it has lots of ways of being deployed to kind of fit the customer’s needs. And I think that’s the wrap-up for me here for this demonstration. The Gateway is a super flexible product. We try to make it super lean and at the same time have lots of capability for our customers to be able to deploy and execute things on their own terms.

Joksan Flores • 30:38

Thank you for watching.