index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Runtime Conditions Profile Guide</title>
    <meta name="description" content="Why Runtime Conditions exists, and a complete profile example, in one place." />
    <link rel="stylesheet" href="assets/styles.css" />
  </head>
  <body>
    <header class="site-header">
      <div class="header-inner">
        <a class="brand" href="index.html">Runtime Conditions</a>
        <nav class="top-links" aria-label="Top links">
          <a href="https://github.com/runtimeconditions/spec/blob/main/docs/sixth-draft.md" data-tip="Read the latest draft of the specification"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/><path d="M9 13h6"/><path d="M9 17h6"/></svg><span>Current Draft</span></a>
          <a href="https://github.com/runtimeconditions/rc-demos/blob/main/README.md" data-tip="Run Runtime Conditions end to end on your own machine"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="10"/><polygon points="10 8 16 12 10 16 10 8"/></svg><span>Run Demo</span></a>
          <a href="reference.html" data-tip="See where each part of this guide comes from in the source repositories"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 6l6-3 6 3 6-3v15l-6 3-6-3-6 3z"/><path d="M9 3v15"/><path d="M15 6v15"/></svg><span>Source Map</span></a>
          <a href="https://github.com/runtimeconditions" data-tip="Browse the Runtime Conditions repositories on GitHub"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg><span>GitHub</span></a>
          <a href="https://cloud-native.slack.com/archives/C0C0R4M65FZ" data-tip="Join the conversation on the CNCF Slack"><svg class="nav-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M4 9h16"/><path d="M4 15h16"/><path d="M10 3L8 21"/><path d="M16 3l-2 18"/></svg><span>Slack</span></a>
        </nav>
      </div>
    </header>

    <div class="guide-layout">
      <aside class="sidebar" aria-label="Guide chapters">
        <p class="sidebar-title">Reader Guide</p>
        <ol class="chapter-list">
          <li><a aria-current="page" href="index.html"><span class="num">00</span><span>Start here</span></a></li>
          <li><a href="concepts.html"><span class="num">01</span><span>Core concepts</span></a></li>
          <li><a href="spec.html"><span class="num">02</span><span>Profile shape</span></a></li>
          <li><a href="developers.html"><span class="num">03</span><span>Code to profile</span></a></li>
          <li><a href="extensions.html"><span class="num">04</span><span>Extensions</span></a></li>
          <li><a href="platform.html"><span class="num">05</span><span>Adapters</span></a></li>
          <li><a href="demo.html"><span class="num">06</span><span>Run the demo</span></a></li>
          <li><a href="reference.html"><span class="num">07</span><span>Reference</span></a></li>
        </ol>
      </aside>

      <main class="content">
        <p class="chapter-label">Start here</p>
        <h1 class="page-title">A guide to Runtime Conditions Profiles.</h1>
        <p class="intro">
          Runtime Conditions Profiles describe the external runtime integrations one workload requires. This guide starts with examples, then walks into the spec, generator, extensions, adapter, and demo.
        </p>
        <div class="note">
          <p>Runtime Conditions is seeking adoption by an established parent project. These repositories are split for hands-on usability, review, demos, and implementation feedback; they are not intended to present Runtime Conditions as a standalone foundation or competing project.</p>
        </div>

        <section class="section">
          <h2>The short version</h2>
          <ol class="step-list">
            <li><span class="step-num">1</span><div><strong>Source code uses integrations.</strong><span>The demo app calls an HTTP API and Redis.</span></div></li>
            <li><span class="step-num">2</span><div><strong>A generator emits a profile.</strong><span>The profile names requirements and environment variable names, not target values.</span></div></li>
            <li><span class="step-num">3</span><div><strong>An adapter fulfills the profile.</strong><span>The Kratix demo maps Conditions to API catalog validation, Redis provisioning, env vars, and Kubernetes resources.</span></div></li>
          </ol>
        </section>

        <section class="section">
          <h2>Example first</h2>
          <div class="example">
            <div class="example-title">
              <span>A complete profile document</span>
              <a href="developers.html">Where this comes from</a>
            </div>
            <pre><code>apiVersion: runtimeconditions.io/v1alpha1
kind: RuntimeConditionsProfile

metadata:
  name: request-logger-http

workload:
  uri: github.com/runtimeconditions/rc-demos/apps/request-logger-http
  version: v0.1.0

extensions:
  - https://runtimeconditions.io/extensions/common-integrations/v1alpha1/runtimeconditions.extension.yaml
  - https://runtimeconditions.io/extensions/env-configuration/v1alpha1/runtimeconditions.extension.yaml

conditions:
  - name: todos-api
    kind: api
    interface:
      type: http
      spec:
        format: openapi
        uri: catalog://api/default/todos-api
        version: 1.0.0
      operations:
        - method: GET
          path: /todos/{id}
    configuration:
      env:
        - property: baseUrl
          name: TODOS_API_URL

  - name: request-cache
    kind: cache
    interface:
      type: key_value
      engine: redis
    configuration:
      alternatives:
        - env:
            - property: url
              name: REDIS_URL
        - env:
            - property: hostname
              name: REDIS_HOST
            - property: port
              name: REDIS_PORT</code></pre>
          </div>
          <div class="note">
            <p>The profile names the workload, declares the extensions needed to interpret its vocabulary, and lists runtime Conditions. It does not contain service URLs, Redis hostnames, credentials, or target-environment choices.</p>
          </div>
        </section>

        <section class="section">
          <h2>Why this exists</h2>
          <p>
            A developer's code needs ordinary things to work - somewhere to store files, somewhere to cache data, a way to call another team's API. None of that is unusual, and the code works fine wherever the developer first tries it. What's unusual is that this knowledge usually only lives in the developer's head, a Slack thread, or an outdated wiki page - never anywhere a machine can read it. So before anything can go live safely, a platform engineer has to dig through all of that by hand, piece it together, and set each need up separately: storage permissions here, a traffic rule there, a certificate somewhere else. Miss one, or get one slightly wrong, and nobody finds out until it's already broken in front of real users.
          </p>
          <p>
            Then it has to happen all over again for the next environment - once for testing, once for the real thing - because none of it was ever connected back to a single source of truth.
          </p>
          <p>
            A Runtime Conditions Profile writes that same intent down once, in plain, machine-readable form - "this needs storage," "this needs a cache," "this needs to call that API." The moment it's submitted, a check runs against it automatically, before the code ever gets a chance to run anywhere - so a missing or invalid requirement is rejected right there, with a clear reason, instead of shipping quietly and breaking later. Once it's accepted, every environment can read that same declaration and fulfill it on its own. Nobody re-derives the same fact by hand, differently, every time.
          </p>
        </section>

        <section class="section">
          <h2>Yes, it's different from Docker Compose</h2>
          <p>
            A lot of teams already write a <code>compose.yaml</code> to describe how their services fit together, so it's a fair question: isn't that the same thing?
          </p>
          <p>
            Not quite. A <code>compose.yaml</code> describes a specific, already-decided implementation - this exact Postgres image, on this exact port, wired up this exact way. Someone reading it still has to reverse-engineer the actual intent behind it: does this really have to be Postgres, or would any relational database work? What about a dependency that has no image at all, like another team's API? You can fake it with a mock, but now whoever's reading your compose file has to guess what that mock is even standing in for.
          </p>
          <p>
            A Runtime Conditions Profile goes the other way around. It never describes a specific implementation - it describes the plain intent: "this needs a cache." It's not tied to any one image, port, or vendor, which is exactly why a platform team can decide the real implementation later, and can change it without the developer rewriting anything. And because the intent is written down cleanly in one place, you could generate a <code>compose.yaml</code> from a Runtime Conditions Profile for local development. Going the other way - guessing a profile out of a compose file - is a lot harder, because the intent was never written down to begin with.
          </p>
        </section>

        <section class="section">
          <h2>How this fits with tools like Radius, Crossplane, and Kratix</h2>
          <p>
            There's a whole category of platform tools already doing real work here - Radius, Score, Porter, Crossplane, Sveltos, Kratix, and others. It's fair to ask where Runtime Conditions fits next to them.
          </p>
          <p>
            The honest answer: it's less about being different from them, and more about how it fits into them. Every one of those tools starts from the same assumption - that you already know what a workload needs before you hand it to them. They're excellent at taking a known requirement and provisioning or wiring up the real thing. What none of them really solve is the step before that: capturing what a workload needs in the first place, in a plain, portable, machine-readable way, written down once by the person who actually knows the answer - the developer.
          </p>
          <p>
            That's the gap a Runtime Conditions Profile fills. It's not a replacement for Radius or Kratix or any tool like them - it's the starting point they all assume you already have. A profile like "this needs storage," "this needs a cache," "this needs to call that API" is exactly the kind of input these tools are built to consume. Runtime Conditions isn't competing for the same job; it's producing the input that job has always needed someone to write down by hand.
          </p>
        </section>

        <section class="section">
          <h2>Read in order</h2>
          <div class="two-col">
            <div class="mini-card">
              <h3>First half: what the profile is</h3>
              <p>Read chapters 2-5 to understand Conditions, profile shape, generator output, and extension vocabulary.</p>
            </div>
            <div class="mini-card">
              <h3>Second half: how it gets used</h3>
              <p>Read chapters 6-8 to understand platform adapters, the working Kratix demo, and where each source file lives.</p>
            </div>
          </div>
        </section>

        <nav class="page-nav" aria-label="Page navigation">
          <span></span>
          <a href="concepts.html">Next: Core concepts</a>
        </nav>
      </main>
    </div>

    <footer class="footer">
      <div class="footer-inner">
        <span>Static GitHub Pages guide for the Runtime Conditions organization.</span>
        <a href="https://github.com/runtimeconditions">GitHub organization</a>
      </div>
    </footer>
    <script src="assets/syntax.js" defer></script>
  </body>
</html>