docs(migrate): add remaining Extending Spinnaker pages

spinnaker · May 13, 2021 · 3835a79 · 3835a79
1 parent 840505d
commit 3835a79
Show file tree

Hide file tree

Showing 17 changed files with 548 additions and 23 deletions.
diff --git a/content/en/docs/guides/developer/extending/_index.md b/content/en/docs/guides/developer/extending/_index.md
@@ -0,0 +1,5 @@
+---
+title: "Extending Spinnaker"
+description: >
+  Guides for extending Spinnaker.
+---
diff --git a/content/en/docs/guides/developer/extending/crd-extensions.md b/content/en/docs/guides/developer/extending/crd-extensions.md
@@ -0,0 +1,141 @@
+---
+title:  "Kubernetes CRD Extensions"
+description: >
+  Explains extension points for deep CRD integrations within Spinnaker.
+---
+
+## Spinnaker Extension Points for Custom Resource Definitions
+
+At Google, we've built extension points for deep CRD integrations within Spinnaker.
+
+This work has allowed us to support the following features within Spinnaker:
+
+ - Custom models for representing CRDs as `spinnakerKinds`
+ - Deploying CRDs with custom Spinnaker artifact types
+ - Custom Kubernetes API versions
+ - Custom Spinnaker naming strategies
+ - Per-account, custom Spinnaker UIs that can run alongside the existing Kubernetes UIs
+
+This guide is for developers who want to duplicate this functionality for their CRDs.
+It also exists as an explanation of certain code paths within Spinnaker which include hooks with no current corresponding open-source implementations.
+
+Developers who want to implement these features will have to build their own layered version
+of [Clouddriver](https://github.com/spinnaker/clouddriver) -
+  see Adam Jorden's [blog post](https://blog.spinnaker.io/scaling-spinnaker-at-netflix-custom-features-and-packaging-e78536d38040) - and should be familiar with the [Kubernetes provider](/reference/providers/kubernetes-v2) and writing code for Clouddriver.
+
+## Custom Handlers
+
+The central extension point is the [KubernetesHandler](https://github.com/spinnaker/clouddriver/blob/master/clouddriver-kubernetes/src/main/java/com/netflix/spinnaker/clouddriver/kubernetes/op/handler/KubernetesHandler.java) class. A subclass of `KubernetesHandler` - e.g., [KubernetesReplicaSetHandler](https://github.com/spinnaker/clouddriver/blob/master/clouddriver-kubernetes/src/main/java/com/netflix/spinnaker/clouddriver/kubernetes/op/handler/KubernetesReplicaSetHandler.java) - defines the
+relationship between Spinnaker and your Kubernetes kind.
+
+For example, if you wanted to build a Spinnaker integration for your CRD of kind `MyCRDKind`, you would start with
+the following handler:
+
+```java
+@Component
+public class MyCRDHandler extends KubernetesHandler {
+
+  public MyCRDHandler() {
+    // Hook point for registering a custom `ArtifactReplacer`
+    // for your CRD. During a deploy operation,
+    // if an artifact of the type specified in the replacer is present,
+    // the artifact will be inserted into the manifest using the
+    // strategy described in the replacer.
+  }
+
+  @Override
+  public KubernetesKind kind() {
+    return KubernetesKind.from("MyCRDKind");
+  }
+
+  @Override
+  public boolean versioned() {
+    // If the CRD resource should be versioned - i.e., assigned a sequence
+    // v001, v002, etc.
+    return false;
+  }
+
+  @Override
+  public SpinnakerKind spinnakerKind() {
+    // The Spinnaker kind that the resource will be represented as in Spinnaker's API and UI.
+    return SpinnakerKind.SERVER_GROUPS;
+  }
+
+  @Override
+  public Status status(KubernetesManifest manifest) {
+    // Includes logic for determining whether your CRD manifest is stable.
+    // A deploy manifest operation, for example, will block until this
+    // method returns a stable status.
+  }
+
+  @Override
+  public KubernetesV2CachingAgentFactory cachingAgentFactory() {
+    return KubernetesCoreCachingAgent::new;
+  }
+}
+```
+
+## Custom Spinnaker Resource Models
+
+You may want to change how their CRD is represented in Spinnaker's API. By default, a CRD of `spinnakerKind` `serverGroups` will
+be represented with the model class [KubernetesV2ServerGroup](https://github.com/spinnaker/clouddriver/blob/master/clouddriver-kubernetes/src/main/java/com/netflix/spinnaker/clouddriver/kubernetes/caching/view/model/KubernetesV2ServerGroup.java).
+
+You may want to override this representation, for example, if you want to define how your server group's `region` is resolved.
+
+To override the default model class, `MyCRDHandler` should implement `ServerGroupHandler` (or `ServerGroupManagerHandler` if your
+resource is of `spinnakerKind` `serverGroupManagers`). You will be responsible for translating raw Spinnaker cache data into a
+subclass of `KubernetesServerGroup`.
+
+## Custom Kubernetes API Versions
+
+If you want Spinnaker to support custom Kubernetes API versions, subclass `KubernetesApiVersion`.
+
+For example,
+
+```java
+public class MyApiVersion extends KubernetesApiVersion {
+  public static MY_BETA_API_VERSION = new MyApiVersion("myApiVersion/v1beta");
+
+  public MyApiVersion(String name) {
+    // Base class maintains state.
+    super(name);
+  }
+}
+```
+
+## Custom Spinnaker Naming Strategies
+
+To use a custom naming strategy for your CRD, implement [NamingStrategy](https://github.com/spinnaker/clouddriver/blob/master/clouddriver-core/src/main/groovy/com/netflix/spinnaker/clouddriver/names/NamingStrategy.java). For example,
+
+```java
+@Component
+public class MyManifestNamer implements NamingStrategy<KubernetesManifest> {
+  @Override
+  public String getName() {
+    return "myManifestNamingStrategy";
+  }
+
+  @Override
+  public void applyMoniker(KubernetesManifest manifest, Moniker moniker) {
+    // Strategy for applying a Spinnaker `Moniker` to a Kubernetes
+    // manifest prior to deployment.
+  }
+
+  @Override
+  public Moniker deriveMoniker(KubernetesManifest manifest) {
+    // Strategy for deriving a Spinnaker `Moniker` from a Kubernetes
+    // manifest.
+  }
+}
+```
+
+This naming strategy can be referenced in a Kubernetes account config. For example:
+
+```
+kubernetes:
+  accounts:
+    - name: my-kubernetes-account
+      namingStrategy: myManifestNamingStrategy
+```
+
+Be careful - this naming strategy will be applied to all manifests manipulated by this account.
diff --git a/content/en/docs/guides/developer/extending/integrate-your-CI/index.md b/content/en/docs/guides/developer/extending/integrate-your-CI/index.md
@@ -4,6 +4,8 @@ description:  >
   This guide explains how to add an integration to other CI providers, so that users leveraging those providers can enjoy the new features.
 ---
 
+## Overview
+
 At Netflix, we built CI integrations to enable features like the Builds view in Spinnaker, fetching artifact metadata and more. You can see the full list of CI features [here](/docs/guides/user/managed-delivery/CI-features).
 
 ## Viewing CI details in Spinnaker
@@ -32,7 +34,7 @@ If you wish to use it, this is what you'll need to do:
 ```
 These endpoints are called by the [CiController](https://github.com/spinnaker/igor/blob/master/igor-web/src/main/java/com/netflix/spinnaker/igor/ci/CiController.java).
 
-Once both of these endpoints are implemented, it should be possible for the installations using that implementation to show CI information in Spinnaker! 
+Once both of these endpoints are implemented, it should be possible for the installations using that implementation to show CI information in Spinnaker!
 If you contribute a new implementation to the project, make sure to include documentation for operators explaining how to enable and configure it in their installation.
 
 
@@ -42,8 +44,8 @@ You can read about how the CI integration enriches the Managed Delivery experien
 
 ### Detecting a new published artifact
 
-When a new artifact is published, `keel` gets notified by `echo` (for Debian packages) or by `igor` (for Docker images). Each artifact has a `metadata` section, which is populated by the corresponding artifact supplier implementation in `keel`. 
-For example, for `docker` artifacts, the `metadata` field is populated by querying `clouddriver`, which stores information from the docker registries configured in the Spinnaker installation. 
+When a new artifact is published, `keel` gets notified by `echo` (for Debian packages) or by `igor` (for Docker images). Each artifact has a `metadata` section, which is populated by the corresponding artifact supplier implementation in `keel`.
+For example, for `docker` artifacts, the `metadata` field is populated by querying `clouddriver`, which stores information from the docker registries configured in the Spinnaker installation.
 
 Here is an example of a Docker artifact event tracked by `keel` (this is a piece of a log statement):
 ```