Skip to content

Commit

Permalink
Update README to align with renaming (#223)
Browse files Browse the repository at this point in the history
  • Loading branch information
@baluchicken
baluchicken authored Sep 29, 2023
1 parent 7fc1918 commit 535005a
Showing 1 changed file with 23 additions and 23 deletions.
46 changes: 23 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,36 @@
## Nasp
## Libnasp

**THIS REPO IS CURRENTLY IN PREVIEW. THE APIS ARE NOT FINAL AND ARE SUBJECT TO CHANGE WITHOUT NOTICE.**

Nasp is an **open-source, lightweight library** to expand service mesh capabilities to non-cloud environments by getting rid of the complexity of operating dedicated network proxies. It is not meant to be a complete service mesh replacement, but rather an extension. It integrates well with an Istio control plane, so applications using Nasp can be handled as standard Istio workloads.
Libnasp is an **open-source, lightweight library** to expand service mesh capabilities to non-cloud environments by getting rid of the complexity of operating dedicated network proxies. It is not meant to be a complete service mesh replacement, but rather an extension. It integrates well with an Istio control plane, so applications using Libnasp can be handled as standard Istio workloads.

Nasp offers the most common functionality of a sidecar proxy, so it eases the developer burden for traffic management, observability, and security. Its range of capabilities includes:
Libnasp offers the most common functionality of a sidecar proxy, so it eases the developer burden for traffic management, observability, and security. Its range of capabilities includes:

- Identity and network traffic security using mutual TLS
- Automatic traffic management features, like HTTP, or gRPC load balancing
- Transparent observability of network traffic, especially standard Istio metrics
- Dynamic configuration through xDS support

To learn more about why we created Nasp, and where it could help, read our introduction [blog](https://techblog.cisco.com/blog/nasp-intro).
To learn more about why we created Libnasp, and where it could help, read our introduction [blog](https://techblog.cisco.com/blog/nasp-intro).

## Architecture

Nasp is primarily a library that can be included in application code to provide service mesh functionality without operating proxies.
But Nasp is also a hybrid model in that it still communicates with a central Istio control plane, and configuration is still declarative and centrally managed. The service discovery, certificate management, and configuration logic aren't handed out to the applications like in a pure library model. These remain the same as with standard Istio - though somewhat limited in functionality.
Libnasp is primarily a library that can be included in application code to provide service mesh functionality without operating proxies.
But Libnasp is also a hybrid model in that it still communicates with a central Istio control plane, and configuration is still declarative and centrally managed. The service discovery, certificate management, and configuration logic aren't handed out to the applications like in a pure library model. These remain the same as with standard Istio - though somewhat limited in functionality.

Therefore Nasp has a minimal component running in a Kubernetes cluster next to an existing Istio control plane. This component is called [Heimdall](./components/heimdall/), and it is the main entry point for a Nasp-enabled application to an existing service mesh. Heimdall automatically injects Istio configuration - like workload metadata, network and mesh settings, or where to receive certificates from - in applications that use Nasp.
Therefore Libnasp has a minimal component running in a Kubernetes cluster next to an existing Istio control plane. This component is called [Heimdall](./components/heimdall/), and it is the main entry point for a Libnasp-enabled application to an existing service mesh. Heimdall automatically injects Istio configuration - like workload metadata, network and mesh settings, or where to receive certificates from - in applications that use Libnasp.

Nasp workloads can run in or outside the service mesh, or the Kubernetes cluster.
Libnasp workloads can run in or outside the service mesh, or the Kubernetes cluster.

![Nasp architecture](./docs/img/nasp-architecture.png)

## Quick start

The quick start will guide you through a common Nasp setup, where an external, Nasp-enabled application is connected to an Istio service mesh running in a Kubernetes cluster. At the end of the example you'll see how a Golang application running on your local machine can send HTTP requests to internal Kubernetes workloads through standard Istio service discovery, using mTLS, but without running an Envoy proxy next to it.
The quick start will guide you through a common Libnasp setup, where an external, Libnasp-enabled application is connected to an Istio service mesh running in a Kubernetes cluster. At the end of the example you'll see how a Golang application running on your local machine can send HTTP requests to internal Kubernetes workloads through standard Istio service discovery, using mTLS, but without running an Envoy proxy next to it.

### Prerequisites

First, we'll need to set up the Kubernetes environment with Istio and the necessary Nasp components.
First, we'll need to set up the Kubernetes environment with Istio and the necessary Libnasp components.
To make it easier, we wrote a script that creates a local [`kind`](https://github.com/kubernetes-sigs/kind) cluster and installs all the requirements.

To get started, simply run the [`deploy-kind.sh`](test/deploy-kind.sh) script in the `test` directory:
Expand All @@ -41,7 +41,7 @@ To get started, simply run the [`deploy-kind.sh`](test/deploy-kind.sh) script in

Once the script finished check if everything is up and running:

1. A standard Istio installation with a control plane and a mesh expansion gateway. By default, Istio is managed by our [istio-operator](https://github.com/banzaicloud/istio-operator/), but upstream Istio installations can also be used with Nasp.
1. A standard Istio installation with a control plane and a mesh expansion gateway. By default, Istio is managed by our [istio-operator](https://github.com/banzaicloud/istio-operator/), but upstream Istio installations can also be used with Libnasp.


```
Expand All @@ -52,7 +52,7 @@ istio-operator-74c544fd8c-vr98s 2/2 Running 0 73
istiod-icp-v115x-7577bf56d-q4r4s 1/1 Running 0 69m
```

2. A [Heimdall](./components/heimdall/) deployment and a Heimdall gatweway. Heimdall is the main entry point for a Nasp-enabled application to an existing service mesh. Heimdall eliminates the need for developers to manually configure Istio settings for applications that use Nasp by authenticating clients and automatically injecting configuration. Read more about Heimdall in its [documentation](./components/heimdall/).
2. A [Heimdall](./components/heimdall/) deployment and a Heimdall gatweway. Heimdall is the main entry point for a Libnasp-enabled application to an existing service mesh. Heimdall eliminates the need for developers to manually configure Istio settings for applications that use Libnasp by authenticating clients and automatically injecting configuration. Read more about Heimdall in its [documentation](./components/heimdall/).

```
> k get pods -n heimdall
Expand All @@ -61,7 +61,7 @@ heimdall-f97745497-jvzws 3/3 Running 2 (69m ago) 69m
heimdall-gw-74c79d5c8-6r6qp 1/1 Running 0 69m
```

3. An `echo` service that's running with an Istio sidecar proxy. It is a test deployment in our Kubernetes cluster we'll send HTTP requests from an external Nasp-enabled client.
3. An `echo` service that's running with an Istio sidecar proxy. It is a test deployment in our Kubernetes cluster we'll send HTTP requests from an external Libnasp-enabled client.

```
> k get pods -n testing
Expand Down Expand Up @@ -120,22 +120,22 @@ Let's see what's inside our Makefile and our Golang code to understand what happ
1. Makefile

The Makefile is very simple: it calls our Golang application with `go run` and passes it the `CLIENT_REQUEST_URL` we've specified above.
The interesting part is that it gets a Nasp authentication token from a Kubernetes secret and passes it to our application:
The interesting part is that it gets a Libnasp authentication token from a Kubernetes secret and passes it to our application:

```
NASP_AUTH_TOKEN ?= $(shell kubectl -n external get secret -l nasp.k8s.cisco.com/workloadgroup=test-http -o jsonpath='{@.items[0].data.token}' | base64 -d)
```

The secret is used by the Nasp library to get the necessary Istio configuration (what network, cluster, or mesh to join, or where to get the required certificates from) for the application from Heimdall.
The secret is used by the Libnasp library to get the necessary Istio configuration (what network, cluster, or mesh to join, or where to get the required certificates from) for the application from Heimdall.
But where is this secret coming from? If you take a look at the end of our init [script](./test/deploy-kind.sh), you'll see that we've created a few `WorkloadGroup` resources.
These are standard [Istio resources](https://istio.io/latest/docs/reference/config/networking/workload-group/) used to describe a set of non-k8s workloads.
[Heimdall](./components/heimdall/) watches these resources and creates corresponding access tokens in Kubernetes secrets for the related external workloads.

For our example, Heimdall needs to be accessible from outside of the cluster. Usually, that is achieved through a Heimdall gateway, whose address is configurable through Nasp. We haven't specified the address in the Makefile because we're using the default value to reach it.
For our example, Heimdall needs to be accessible from outside of the cluster. Usually, that is achieved through a Heimdall gateway, whose address is configurable through Libnasp. We haven't specified the address in the Makefile because we're using the default value to reach it.

2. Golang code

Now let's see what we did in our Golang code to make the HTTP requests we're sending go through Nasp.
Now let's see what we did in our Golang code to make the HTTP requests we're sending go through Libnasp.

First, we import the library:

Expand Down Expand Up @@ -164,7 +164,7 @@ if err := iih.Run(ctx); err != nil {
}
```

And finally, we send the HTTP request through the Nasp transport layer we get from the `IstioIntegrationHandler`:
And finally, we send the HTTP request through the Libnasp transport layer we get from the `IstioIntegrationHandler`:

```go
transport, err := iih.GetHTTPTransport(http.DefaultTransport)
Expand All @@ -189,13 +189,13 @@ if err != nil {

## Other examples

In the [`examples`](./examples) directory we have similar examples of how to use Nasp with HTTP, gRPC, or TCP connections from Golang.
All examples can be run either as servers or clients. Refer to the `Makefiles` on how to run these examples, and check out the Golang code to learn how to use Nasp for specific protocols.
In the [`examples`](./examples) directory we have similar examples of how to use Libnasp with HTTP, gRPC, or TCP connections from Golang.
All examples can be run either as servers or clients. Refer to the `Makefiles` on how to run these examples, and check out the Golang code to learn how to use Libnasp for specific protocols.

## Support for other languages

The core code of Nasp is written in Golang, therefore the main examples are also written in Go.
However, Nasp could also be imported from other languages with the help of C bindings generated from the core codebase.
The core code of Libnasp is written in Golang, therefore the main examples are also written in Go.
However, Libnasp could also be imported from other languages with the help of C bindings generated from the core codebase.
A thin shim layer still has to be written for specific platforms, but the core functionality is unchanged.

Currently, supported languages and frameworks are:
Expand All @@ -206,4 +206,4 @@ Currently, supported languages and frameworks are:

## Issues and contributions

We use GitHub to track issues and accept contributions. If you'd like to raise an issue or open a pull request with changes, refer to our [contribution guide](./CONTRIBUTING.md).
We use GitHub to track issues and accept contributions. If you'd like to raise an issue or open a pull request with changes, refer to our [contribution guide](./CONTRIBUTING.md).

0 comments on commit 535005a

Please sign in to comment.