concepts.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Core Concepts | Runtime Conditions</title>
    <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 href="index.html"><span class="num">00</span><span>Start here</span></a></li>
          <li><a aria-current="page" 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">Chapter 1</p>
        <h1 class="page-title">Profiles describe demand. Platforms decide fulfillment.</h1>
        <p class="intro">
          The profile is the portable contract between application intent and platform automation.
        </p>

        <section class="section">
          <h2>Demand in a complete profile</h2>
          <div class="example">
            <div class="example-title">Full profile shape with one cache Condition</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: 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>
        </section>

        <section class="section">
          <h2>Fulfillment outside the profile</h2>
          <p class="short">
            The profile says the workload needs a Redis-compatible cache and can consume it through <code>REDIS_URL</code> or <code>REDIS_HOST</code> plus <code>REDIS_PORT</code>. Before Kubernetes can inject <code>REDIS_URL</code>, an adapter has to satisfy that Condition by provisioning Redis or granting access to an existing Redis cache.
          </p>
          <ol class="step-list" aria-label="Redis fulfillment steps">
            <li>
              <span class="step-num">1</span>
              <div>
                <strong>Profile</strong>
                <span>Declares <code>kind: cache</code>, <code>engine: redis</code>, and acceptable env vars.</span>
              </div>
            </li>
            <li>
              <span class="step-num">2</span>
              <div>
                <strong>Adapter</strong>
                <span>Chooses how this platform can satisfy the cache Condition.</span>
              </div>
            </li>
            <li>
              <span class="step-num">3</span>
              <div>
                <strong>Provider</strong>
                <span>Creates Redis or grants access to an existing Redis instance.</span>
              </div>
            </li>
            <li>
              <span class="step-num">4</span>
              <div>
                <strong>Connection Output</strong>
                <span>Publishes <code>url</code>, <code>hostname</code>, and <code>port</code> through platform artifacts.</span>
              </div>
            </li>
            <li>
              <span class="step-num">5</span>
              <div>
                <strong>Deployment</strong>
                <span>Receives the env var names declared by the workload profile.</span>
              </div>
            </li>
          </ol>
          <p class="short">
            In the Kratix demo, the Redis Promise is the provider interface. The adapter emits a Redis request, derives the service address, and binds the profile's <code>REDIS_URL</code> request into the generated Deployment.
          </p>
          <div class="example">
            <div class="example-title">Provider request emitted by the adapter</div>
            <pre><code>apiVersion: platform.demoteam.io/v1alpha1
kind: Redis
metadata:
  name: request-logger-cache
  namespace: demo
  labels:
    kratix.io/component-of-promise-name: application-release
spec:
  size: small</code></pre>
          </div>
          <div class="example">
            <div class="example-title">Final Deployment env generated by the adapter</div>
            <pre><code>apiVersion: apps/v1
kind: Deployment
metadata:
  name: request-logger-http
  namespace: demo
spec:
  # ...
  template:
    spec:
      containers:
        - name: request-logger-http
          # ...
          env:
            - name: REDIS_URL
              value: redis://request-logger-cache.demo.svc.cluster.local:6379
            - name: REDIS_HOST
              value: request-logger-cache.demo.svc.cluster.local
            - name: REDIS_PORT
              value: "6379"</code></pre>
          </div>
          <p class="short">
            This snippet belongs in the generated Kubernetes Deployment. It is not part of the Runtime Conditions Profile. It is the result of the adapter satisfying the profile against a concrete platform.
          </p>
        </section>

        <section class="section">
          <h2>Vocabulary</h2>
          <div class="table-wrap">
            <table>
              <thead>
                <tr><th>Term</th><th>Meaning</th><th>Demo Example</th></tr>
              </thead>
              <tbody>
                <tr><td>Profile</td><td>One workload's runtime integration requirements.</td><td>`request-logger-http` generated profile</td></tr>
                <tr><td>Condition</td><td>One required external integration.</td><td>`todos-api`, `request-cache`, `s3-object-store`</td></tr>
                <tr><td>Extension</td><td>Vocabulary and validation outside the core spec.</td><td>Common Integrations, Env Configuration, AWS Object Store</td></tr>
                <tr><td>Generator</td><td>Reads code and emits a profile.</td><td>Go AST generator</td></tr>
                <tr><td>Adapter</td><td>Maps valid profiles to platform-specific requests.</td><td>Kratix `ApplicationRelease` Promise</td></tr>
              </tbody>
            </table>
          </div>
        </section>

        <section class="section">
          <h2>What never belongs in the profile</h2>
          <ul class="horizontal-list">
            <li class="mini-card"><strong>Secret values</strong><span>Access keys, tokens, passwords, and private material stay out.</span></li>
            <li class="mini-card"><strong>Target choices</strong><span>Bucket names, service names, cloud accounts, and cluster topology stay out.</span></li>
            <li class="mini-card"><strong>Provisioning instructions</strong><span>The profile declares requirements. Adapters and platforms provision or bind resources.</span></li>
          </ul>
        </section>

        <nav class="page-nav" aria-label="Page navigation">
          <a href="index.html">Previous: Start here</a>
          <a href="spec.html">Next: Profile shape</a>
        </nav>
      </main>
    </div>

    <footer class="footer">
      <div class="footer-inner">
        <span>Chapter 1 of 7</span>
        <a href="spec.html">Continue</a>
      </div>
    </footer>
    <script src="assets/syntax.js" defer></script>
  </body>
</html>