diff --git a/design/20200305-spec-v1alpha2-dependency-parampassing.md b/design/20200305-spec-v1alpha2-dependency-parampassing.md index e4dbb82..9e9c926 100644 --- a/design/20200305-spec-v1alpha2-dependency-parampassing.md +++ b/design/20200305-spec-v1alpha2-dependency-parampassing.md @@ -5,7 +5,13 @@ ## Background In https://github.com/oam-dev/spec/issues/171, we have discussed our dependency stories and started to explore solutions. -Now that we have designed and implemented mechanism to satisfy dependency requirements, we are proposing to add them into OAM spec. +Now that we have implemented and evolved the design to solve real world problems, we are proposing the design to OAM spec. + +## Goals + +In this design, we want to help applications reduce the burden of handling fault tolerance and dependency health. +By putting this work in the OAM platform layer, OAM users can define explicit dependency and parameter passing in a standard way +without carign about the implementation details. ## Use Cases @@ -14,22 +20,23 @@ Now that we have designed and implemented mechanism to satisfy dependency requir Two components, MySQL and Web exists in the same AppConfig and Web depends on MySQL that: 1. MySQL needs to start first; -2. MySQL connection info needs to be injected into Web's environment variables or files; +2. Web depends on connection credentials from MySQL Component. Once MySQL has started, the credentials will be injected into Web component's environment variables via service binding. ### Case 2: NAS FileSystem and MountTarget -Two components, NAS_FileSystem and NAS_MountTarget exists in the same AppConfig and NAS_MountTarget depends on NAS_FileSystem that: +Two components, NAS_FileSystem and NAS_MountTarget exists in the same _ApplicationConfiguration_ and NAS_MountTarget depends on NAS_FileSystem that: 1. NAS_FileSystem needs to be created first; -2. NAS_MountTarget needs filesystemID from NAS_FileSystem to fill in NAS_MountTarget's spec. +2. NAS_MountTarget depends on filesystemID from NAS_FileSystem to fill in NAS_MountTarget's spec. ## Proposal -### Component and Trait Dependency +### Component Dependency -We are proposing to add `dependencies` in AppConfig as follows: +For use case 1 and 2, we are proposing to add `dependencies` in _ApplicationConfiguration_ which a component can describe its dependent components. ```yaml +apiVersion: core.oam.dev/v1alpha2 kind: ApplicationConfiguration spec: - components: @@ -37,39 +44,38 @@ spec: - componentName: web dependencies: - mysql +--- +kind: ApplicationConfiguration +spec: +- components: + - componentName: nas-file-system + - componentName: nas-mount-target + dependencies: + - nas-file-system ``` -Here a component can describe its dependencies, or dependent components. +### Trait Ordering -For Case 1, we also suggest to use ServiceBinding in [trait-injector](https://github.com/oam-dev/trait-injector) to inject secret. It is a trait that should be applied before component starts. We propose to add `ordering` to express trait's ordering w.r.t the component. +For use case 1, we are using a trait called [ServiceBinding](https://github.com/oam-dev/trait-injector) to auto-bind credentials. ServiceBinding trait should be applied before component starts. We propose to add `stage` in TraitDefinition to express ordering relationship with the workload: ```yaml -- componentName: web - dependencies: - - mysql - traits: - - ordering: preStart # applied before component starts - trait: - kind: ServiceBinding - spec: - bindings: - - from: - secret: - name: mysql-conn - to: # inject into Web Deployment's file path - filePath: /input/mysql-conn +apiVersion: core.oam.dev/v1alpha2 +kind: TraitDefinition +spec: + appliesToWorkloads: + - core.oam.dev/v1alpha2.ContainerizedWorkload + stage: preStart # other options: postStart | preStop | postStop ``` ### Parameter Passing -For Case 2, while the above mechanism can provide the dependency ordering, it doesn't fulfill the parameter passing requirement. As a result, we propose to extend _ParameterValue_ to accept value from another component's field: - +For use case 2, the filesystemID from NasFileSystem's status needs to be passed to NasMountTarget's spec. To solve this problem, we propose to extend _ParameterValue_ to accept value from another component's field: ```yaml kind: ApplicationConfiguration spec: components: - - componentName: nas-file-system # The resource of nas-file-system output a filesystemID at .status.filesystemID + - componentName: nas-file-system # The Workload of nas-file-system output a filesystemID at .status.filesystemID - componentName: nas-mount-target dependencies: @@ -77,7 +83,7 @@ spec: parameterValues: - name: filesystem-id from: - compoentName: nas-file-system + compoent: nas-file-system fieldPath: ".status.filesystemID" # take the field's value from nas-file-system's workload --- apiVersion: core.oam.dev/v1alpha2