Update deployment configuration reference (#585)

**What this PR does / why we need it**:

**Which issue(s) this PR fixes**:

Fixes #

**Does this PR introduce a user-facing change?**:
<!--
If no, just write "NONE" in the release-note block below.
-->
```release-note
NONE
```

This PR was merged by Kapetanios.

docs/content/en/docs/contributor-guide/piped-development.md

@@ -18,10 +18,14 @@ In order to run `piped` at the local environment for debugging while development
 we prepared a fake control-plane to be used.
 
 1. Prepare a `.dev` directory at the root of repository that contains:
-- a `piped.key` file with a fake key (e.g. `"hello-pipecd"`)
-- a piped configuration file `piped-config.yaml` (e.g. [pkg/config/testdata/piped/dev-config.yaml](https://github.com/pipe-cd/pipe/blob/master/pkg/config/testdata/piped/dev-config.yaml))
+- A `piped.key` file with a fake key as the following
+  ```
+  hello-pipecd
+  ```
 
-2. Ensure that your `kube-context` is connecting to right kubernetes cluster
+- A piped configuration file `piped-config.yaml`
+
+2. Ensure that your `kube-context` is connecting to the right kubernetes cluster
 
 2. Run the following command to start running `piped`
 
@@ -33,5 +37,5 @@ bazelisk run --run_under="cd $PWD && " //cmd/piped:piped -- piped \
 --piped-id=local-dev-piped \
 --piped-key-file=.dev/piped.key \
 --bin-dir=/tmp/piped-bin \
---config-file=pkg/config/testdata/piped/dev-config.yaml
+--config-file=.dev/dev-config.yaml
 ```

docs/content/en/docs/overview/_index.md

@@ -20,7 +20,7 @@ Component Architecture
 
 ![](/images/deployment-details.png)
 <p style="text-align: center;">
-Deployment Details Screen
+Deployment Details Page
 </p>
 
 ## Why PipeCD?

docs/content/en/docs/user-guide/configuration-reference.md

@@ -6,8 +6,6 @@ description: >
   This page describes all configurable fields in the deployment configuration and analysis template.
 ---
 
-> TBA
-
 ## Kubernetes Application
 
 ``` yaml
@@ -113,7 +111,7 @@ spec:
 | name | string | One of the provided stage names. | Yes |
 | desc | string | The description about the stage. | No |
 | timeout | duration | The maximum time the stage can be taken to run. | No |
-| with | | Specific configuration for the stage. | No |
+| with | [StageOptions](/docs/user-guide/configuration-reference/#stageoptions) | Specific configuration for the stage. This must be one of these [StageOptions](/docs/user-guide/configuration-reference/#stageoptions). | No |
 
 ## KubernetesDeploymentInput
 
@@ -133,11 +131,20 @@ spec:
 
 | Field | Type | Description | Required |
 |-|-|-|-|
+| gitRemote | string | Git remote address where the chart is placing. Empty means the same repository. | No |
+| ref | string | The commit SHA or tag value. Only valid when gitRemote is not empty. | No |
+| path | string | Relative path from the repository root to the chart directory. | No |
+| repository | string | The name of a registered Helm Chart Repository. | No |
+| name | string | The chart name. | No |
+| version | string | The chart version. | No |
 
 ## HelmOptions
 
 | Field | Type | Description | Required |
 |-|-|-|-|
+| releaseName | string | The release name of helm deployment. By default the release name is equal to the application name. | No |
+| valueFiles | []string | List of value files should be loaded. | No |
+| setFiles | []string | List of file path for values. | No |
 
 ## KubernetesQuickSync
 
@@ -163,13 +170,22 @@ spec:
 
 | Field | Type | Description | Required |
 |-|-|-|-|
-| method | string | Which traffic routing method will be used. Avaiable values are `istio`, `podselector`. Default is `podselector`. | No |
+| method | string | Which traffic routing method will be used. Avaiable values are `istio`, `smi`, `podselector`. Default is `podselector`. | No |
 | istio | [IstioTrafficRouting](/docs/user-guide/configuration-reference/#istiotrafficrouting)| Istio configuration when the method is `istio`. | No |
 
 ## IstioTrafficRouting
 
 | Field | Type | Description | Required |
 |-|-|-|-|
+| editableRoutes | []string | List of routes in the VirtualService that can be changed to update traffic routing. Empty means all routes should be updated. | No |
+| host | string | The service host. | No |
+| virtualService | [IstioVirtualService](/docs/user-guide/configuration-reference/#istiovirtualservice) | The reference to VirtualService manifest. Empty means the first VirtualService resource will be used. | No |
+
+## IstioVirtualService
+
+| Field | Type | Description | Required |
+|-|-|-|-|
+| name | string | The name of VirtualService manifest. | No |
 
 ## TerraformDeploymentInput
 
@@ -224,6 +240,7 @@ spec:
 
 | Field | Type | Description | Required |
 |-|-|-|-|
+| | | | |
 
 ### KubernetesBaselineRolloutStageOptions
 
@@ -237,6 +254,7 @@ spec:
 
 | Field | Type | Description | Required |
 |-|-|-|-|
+| | | | |
 
 ### KubernetesTrafficRoutingStageOptions
 

pkg/app/piped/executor/kubernetes/traffic.go

@@ -45,7 +45,7 @@ func (e *Executor) ensureTrafficRouting(ctx context.Context) model.StageStatus {
 		e.LogPersister.Errorf("Malformed configuration for stage %s", e.Stage.Name)
 		return model.StageStatus_STAGE_FAILURE
 	}
-	method := config.DetermineTrafficRoutingMethod(e.config.TrafficRouting)
+	method := config.DetermineKubernetesTrafficRoutingMethod(e.config.TrafficRouting)
 
 	// Load the manifests at the triggered commit.
 	e.LogPersister.Infof("Loading manifests at commit %s for handling", commitHash)
@@ -88,7 +88,7 @@ func (e *Executor) ensureTrafficRouting(ctx context.Context) model.StageStatus {
 	trafficRoutingManifest := trafficRoutingManifests[0]
 
 	// In case we are routing by PodSelector, the service manifest must contain variantLabel inside its selector.
-	if method == config.TrafficRoutingMethodPodSelector {
+	if method == config.KubernetesTrafficRoutingMethodPodSelector {
 		if err := checkVariantSelectorInService(trafficRoutingManifest, primaryVariant); err != nil {
 			e.LogPersister.Errorf("Traffic routing by PodSelector requires %q inside the selector of Service manifest but it was unable to check that field in manifest %s (%v)",
 				variantLabel+": "+primaryVariant,
@@ -127,10 +127,10 @@ func (e *Executor) ensureTrafficRouting(ctx context.Context) model.StageStatus {
 	return model.StageStatus_STAGE_SUCCESS
 }
 
-func findTrafficRoutingManifests(manifests []provider.Manifest, serviceName string, cfg *config.TrafficRouting) ([]provider.Manifest, error) {
-	method := config.DetermineTrafficRoutingMethod(cfg)
+func findTrafficRoutingManifests(manifests []provider.Manifest, serviceName string, cfg *config.KubernetesTrafficRouting) ([]provider.Manifest, error) {
+	method := config.DetermineKubernetesTrafficRoutingMethod(cfg)
 
-	if method == config.TrafficRoutingMethodIstio {
+	if method == config.KubernetesTrafficRoutingMethodIstio {
 		istioConfig := cfg.Istio
 		if istioConfig == nil {
 			istioConfig = &config.IstioTrafficRouting{}
@@ -141,8 +141,8 @@ func findTrafficRoutingManifests(manifests []provider.Manifest, serviceName stri
 	return findManifests(provider.KindService, serviceName, manifests), nil
 }
 
-func (e *Executor) generateTrafficRoutingManifest(manifest provider.Manifest, primaryPercent, canaryPercent, baselinePercent int, cfg *config.TrafficRouting) (provider.Manifest, error) {
-	if cfg != nil && cfg.Method == config.TrafficRoutingMethodIstio {
+func (e *Executor) generateTrafficRoutingManifest(manifest provider.Manifest, primaryPercent, canaryPercent, baselinePercent int, cfg *config.KubernetesTrafficRouting) (provider.Manifest, error) {
+	if cfg != nil && cfg.Method == config.KubernetesTrafficRoutingMethodIstio {
 		istioConfig := cfg.Istio
 		if istioConfig == nil {
 			istioConfig = &config.IstioTrafficRouting{}

pkg/config/deployment_kubernetes.go

@@ -36,7 +36,7 @@ type KubernetesDeploymentSpec struct {
 	//   name: replication-controller-name
 	Workloads []K8sResourceReference `json:"workloads"`
 	// Which method should be used for traffic routing.
-	TrafficRouting *TrafficRouting `json:"trafficRouting"`
+	TrafficRouting *KubernetesTrafficRouting `json:"trafficRouting"`
 }
 
 func (s *KubernetesDeploymentSpec) GetStage(index int32) (PipelineStage, bool) {
@@ -81,55 +81,64 @@ type KubernetesDeploymentInput struct {
 }
 
 type InputHelmChart struct {
-	// Empty means current repository.
+	// Git remote address where the chart is placing.
+	// Empty means the same repository.
 	GitRemote string `json:"gitRemote"`
 	// The commit SHA or tag for remote git.
 	Ref string `json:"ref"`
 	// Relative path from the repository root directory to the chart directory.
 	Path string `json:"path"`
 
-	// The name of an added Helm chart repository.
+	// The name of an added Helm Chart Repository.
 	Repository string `json:"repository"`
 	Name       string `json:"name"`
 	Version    string `json:"version"`
 }
 
 type InputHelmOptions struct {
+	// The release name of helm deployment.
 	// By default the release name is equal to the application name.
 	ReleaseName string `json:"releaseName"`
 	// List of value files should be loaded.
 	ValueFiles []string `json:"valueFiles"`
-	SetFiles   map[string]string
+	// List of file path for values.
+	SetFiles map[string]string
 }
 
-type TrafficRoutingMethod string
+type KubernetesTrafficRoutingMethod string
 
 const (
-	TrafficRoutingMethodPodSelector TrafficRoutingMethod = "podselector"
-	TrafficRoutingMethodIstio       TrafficRoutingMethod = "istio"
+	KubernetesTrafficRoutingMethodPodSelector KubernetesTrafficRoutingMethod = "podselector"
+	KubernetesTrafficRoutingMethodIstio       KubernetesTrafficRoutingMethod = "istio"
+	KubernetesTrafficRoutingMethodSMI         KubernetesTrafficRoutingMethod = "smi"
 )
 
-type TrafficRouting struct {
-	Method TrafficRoutingMethod `json:"method"`
-	Istio  *IstioTrafficRouting `json:"istio"`
+type KubernetesTrafficRouting struct {
+	Method KubernetesTrafficRoutingMethod `json:"method"`
+	Istio  *IstioTrafficRouting           `json:"istio"`
 }
 
-// DetermineTrafficRoutingMethod determines the routing method should be used based on the TrafficRouting config.
+// DetermineKubernetesTrafficRoutingMethod determines the routing method should be used based on the TrafficRouting config.
 // The default is PodSelector: the way by updating the selector in Service to switching all of traffic.
-func DetermineTrafficRoutingMethod(cfg *TrafficRouting) TrafficRoutingMethod {
+func DetermineKubernetesTrafficRoutingMethod(cfg *KubernetesTrafficRouting) KubernetesTrafficRoutingMethod {
 	if cfg == nil {
-		return TrafficRoutingMethodPodSelector
+		return KubernetesTrafficRoutingMethodPodSelector
 	}
 	if cfg.Method == "" {
-		return TrafficRoutingMethodPodSelector
+		return KubernetesTrafficRoutingMethodPodSelector
 	}
 	return cfg.Method
 }
 
 type IstioTrafficRouting struct {
+	// List of routes in the VirtualService that can be changed to update traffic routing.
+	// Empty means all routes should be updated.
 	EditableRoutes []string `json:"editableRoutes"`
 	// TODO: Add a validate to ensure this was configured or using the default value by service name.
-	Host           string               `json:"host"`
+	// The service host.
+	Host string `json:"host"`
+	// The reference to VirtualService manifest.
+	// Empty means the first VirtualService resource will be used.
 	VirtualService K8sResourceReference `json:"virtualService"`
 }
 

pkg/config/deployment_test.go

@@ -113,8 +113,8 @@ func TestAppConfig(t *testing.T) {
 						},
 					},
 				},
-				TrafficRouting: &TrafficRouting{
-					Method: TrafficRoutingMethodPodSelector,
+				TrafficRouting: &KubernetesTrafficRouting{
+					Method: KubernetesTrafficRoutingMethodPodSelector,
 				},
 			},
 			expectedError: nil,