Feature announcement: Catalog of Resource Classes

One of the fundamentals of developer self-service in platform engineering is the discoverability of available options. Developers can only use resources they know exist, and it’s the Platform Engineers' responsibility to spread that knowledge effectively. Manually maintained documentation requires constant maintenance effort and often quickly gets out of sync with reality. 

That is why we are excited to introduce the Catalog of Resource Classes, a solution to this problem.

What are Resource Classes?

While it’s usually impossible to satisfy an entire organization's needs with only one configuration of a PostgreSQL database or S3 bucket, going too far in the other direction can be equally disruptive. The number of unique flavors a platform team may need to maintain can quickly get out of hand. At the same time, developers will also have to either configure these resources themselves or express specific requirements usually outside their expertise which distracts them from their main priority: adding value to the business.

Resource Classes in the Humanitec Platform Orchestrator offer a balanced approach that provides a set of options within each Resource Type in a way that doesn’t overload developers with unnecessary technical details. For example, based on the services built within a company, the platform team identified a need for four Resource Classes of S3 buckets:

• A default S3 bucket might be the standard configuration that is compliant with all security requirements and matches 80% of the developers’ use cases.
• An external S3 bucket might be open to the public internet, e.g. to allow for asset downloading.
• A sensitive S3 bucket might be configured to be encrypted and only accessible via a limited set of roles, e.g. for services storing confidential data.
• A volatile S3 bucket might be configured with a retention time of less than 24 hours, e.g., for holding intermediate data from other processes.

Although an S3 bucket will be provisioned in all those cases, they’ll have a different configuration that matches their designated use case. 

Developers should be required to know only which resource they need and for what use case. Everything else, like the specifics of those different configurations or how to set them up, is an unnecessary cognitive load. This is the experience that the Catalog of Resource Classes provides. 

Catalog of Resource Classes

With the introduction of the Catalog of Resource Classes, the Platform Engineering team can create required classes with descriptions explaining each class’ purpose and match them to the right Resource Definitions. 

For platform teams

The Classes section in the Humanitec Portal Resources allows you to inspect which Classes exist and review which Resource Definition they are matched to.

As you can see, two Resource Definitions use the sensitive Class. The extra encryption and security requirements make this type of S3 bucket more expensive to provision. Knowing that sensitive data cannot be used in development environments, the platform team decides to use standard S3 buckets in the testing environments. This change is made through Matching Criteria.

With this configuration, developers' workload definition, which is environment-agnostic by design, remains unchanged regardless of the environment in which it is deployed. The Platform Orchestrator ensures the correct S3 bucket is provisioned in each context.

For developers

This is how this resource dependency using a sensitive class would look from the developer’s perspective in a Score file describing the workload specification. 

apiVersion: score.dev/v1b1
...
resources:
  storage:
    type: s3
    class: sensitive
    

As mentioned above, this self-service model only works if developers can quickly determine the currently available options, specifically in this case: what to write in the resources part of their Score file. All classes from the catalog will generate a list accessible to developers through UI, VSCode extension, and CLI.

The introduction of the Catalog of Resource Classes also improved the validation that the Humanitec CLI and the VSCode extension provide for Score files. In case of a spelling mistake or the usage of a deprecated Class, the CLI will show either a warning or throw an error if --strict flag is used.

Developers can then use the CLI to list all available Resource Types and Classes to fix the issue and continue working without asking the Platform Team for help.

Conclusions

Your platform's self-service capabilities will only be effective if they’re discoverable by the end users. Humanitec’s Resource Classes allow Platform Engineering teams to provide a broader range of resources in the Platform while remaining in control of the variance, and at the same time, the Catalog takes care of their visibility to Developers.

To learn more about building an ideal Resource system in Humanitec, ​​join our upcoming workshops or talk to a platform architect.