Steeltoe Samples is a gallery of runnable cloud Foundry applications

One folder per Steeltoe component

The repository is a collection of sample applications illustrating how to use the Steeltoe framework, and it is organised by the Steeltoe area rather than by application. The top level of the README links to six of them.

`Configuration` holds samples using the Spring Cloud Config Server and other Steeltoe configuration providers. `Discovery` holds samples using Steeltoe Service Discovery in microservices-based applications. `Management` holds samples using the Steeltoe Management packages for adding Management REST endpoints to your application, as well as adding Distributed Tracing support. `Connectors` holds samples using the Steeltoe Connectors for connecting to backing services. `FileShares` has a single sample using Steeltoe to manage the connection with a Windows, or SMB, network file share. `Security` holds samples using the Steeltoe Security packages for Authentication and Authorization with Cloud Foundry auth services and using a Redis cache for DataProtection KeyRing storage.

The language is C#, the licence is Apache 2.0 with a `License.txt` in the root, the homepage is steeltoe.io, and the repository is not archived with the last push on 2026-10-09. There are no GitHub releases, which for a samples repository is not surprising, since the thing being released is Steeltoe itself rather than these applications.

The pattern is familiar from other .NET framework ecosystems. A framework team keeps a set of working applications that demonstrate each feature, and those applications double as acceptance tests for the framework.

Configuration and Discovery are the entry points

The two directories a newcomer should look at first are the ones that cover the plumbing.

Configuration is about where an application gets its settings. The samples use the Spring Cloud Config Server and other Steeltoe configuration providers, which means the same application can be pointed at different configuration sources without changing code. In a Cloud Foundry deployment this is how an application receives the credentials and settings for the services it is bound to.

Discovery is about finding other services. The samples use Steeltoe Service Discovery in microservices-based applications, so a service registers itself and looks up its peers by name instead of by address. The pairing of the two directories is the point: a microservice that consumes a backing service needs both, configuration to know where the backing service is and discovery to route to it.

That pairing is also why the Connectors directory exists. If configuration gives you the settings and discovery gives you the address, a connector is the part that turns a set of credentials into a configured client for a specific service, and the connectors samples show that last step for Cloud Foundry based services.

Management is where observability and tracing live

The Management samples cover two separate things that the directory name makes easy to miss.

The first is Management REST endpoints, which is Steeltoe's way of exposing the operational surface of an application, the health and metrics and similar endpoints that a platform or a monitoring system can scrape. The second is Distributed Tracing support, which is the instrumentation that lets a request be followed across service boundaries.

These two are grouped because they solve the same class of problem from different directions. The endpoints tell you the state of one service, and the tracing tells you the path of a request through several of them. For an application running on Cloud Foundry, both matter, because the platform is the thing consuming the endpoints and the place where a trace of a call that crossed a service boundary becomes interesting.

The samples are also where the gap between a library and a platform shows up. A management endpoint set only makes sense if something is calling it, and a trace only tells a story if the hops are instrumented on both sides. A sample application wires that up end to end, which is exactly the part that a component reference does not show.

Connectors and FileShares cover the boring parts

The Connectors samples demonstrate what the Steeltoe Connectors are for, and the README states the benefit in one sentence: they simplify the coding process of binding to and accessing Cloud Foundry based services.

That word binding is the important one. On a platform, a service instance is bound to an application, and the application is expected to read the connection details from the environment rather than from a configuration file. A connector is the code that does that read and hands you a client already set up. The samples therefore demonstrate fewer application logic and more the moment of binding, which is the part teams get wrong on their first attempt.

The FileShares sample is a single application rather than a set, and it covers something quite specific: using Steeltoe to manage the connection with a Windows, or SMB, network file share. That is a case where the framework is doing connection management rather than serving an API, and it is a reasonable place to look if your service needs to read and write a file share from a .NET application running elsewhere.

The Security samples then close the loop, with Authentication and Authorization against Cloud Foundry auth services and a Redis cache used for DataProtection KeyRing storage, which is the piece that matters when a service has to keep encryption keys across restarts and across instances.

main is the moving target, 3.x is the released line

The Branches section is short and is the first thing to read if you are planning to copy anything from here.

All new development is done on the main branch. Samples for released Steeltoe versions can be found in their respective branches, and the example given is that the branch `3.x` contains samples for the latest Steeltoe 3.x release.

The practical implication is that main is where work in progress lives, and the version branches are where the samples match a shipped Steeltoe. If you are running Steeltoe 3.x in production, the samples in the `3.x` branch are the ones that correspond to the framework you actually have, and the ones on main may use APIs that have moved on.

That pattern is sensible and it is also the reason the repository has to be read carefully rather than cloned. The samples on main are the best illustration of what the framework can do, and the samples on a version branch are the ones that will compile against what you have installed.

The build instructions are per sample, and the test harness is Python

The README does not describe how to build the repository, and it says why. It points to the individual sample READMEs linked above for instructions on how to build and run each specific application.

That is the right structure for a gallery, and it has a cost: there is no single command, and each sample brings its own expectations, which for a Cloud Foundry framework means credentials, a config server, a service registry and a backing service instance. You will be reading several READMEs rather than one.

The repository layout also shows that the samples are tested, not just written. Alongside the six sample directories there is a Python test harness: a `Pipfile` and `Pipfile.lock`, `behave.ini` with `behave.sh` and `behave.ps1` wrappers, an `environment.py`, a `pysteel/` package, `steps/` for the behaviour steps, `tools/`, a `logging.ini`, a `nuget.config`, a `pyenv.pkgs` file and a `user.ini.example`, plus an `.libexec/` directory. There is also `CommonTasks.md`, `TESTS.md` and a `CONTRIBUTING.md`.

So the samples are exercised by acceptance tests driven from Python, which is a reasonable way to keep a gallery of cloud applications honest, since each one needs a real environment rather than a unit test.

One limitation follows from all this. These are reference applications with their own dependencies, not a starter template. They show the wiring for one Steeltoe area in isolation, and taking one as the skeleton of a production service means removing the parts that demonstrate the feature and adding the parts that a real service needs.

Editorial conclusion

Adopt Steeltoe Samples when you are building a service on Steeltoe and want to see a working example of the wiring for one specific area, and when you can pick the branch that matches your Steeltoe version. Do not adopt it as a project template, since the samples are demonstrations rather than a maintained application skeleton, and do not plan from the main branch if you are shipping. Verify first that the branch you copy corresponds to a Steeltoe release you actually use, that the sample's own README covers the build steps, and that the service bindings it expects, Cloud Foundry credentials, a config server, a Redis instance, exist in the environment you are moving it into.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. SteeltoeOSS/Samples on GitHub