Merge branch 'docs-for-auto-stop-environments' into 'master'

Publish "Auto stop environments after a certain period"

See merge request gitlab-org/gitlab!24850

app/controllers/projects/environments_controller.rb

@@ -16,7 +16,7 @@ class Projects::EnvironmentsController < Projects::ApplicationController
     push_frontend_feature_flag(:prometheus_computed_alerts)
   end
   before_action do
-    push_frontend_feature_flag(:auto_stop_environments)
+    push_frontend_feature_flag(:auto_stop_environments, default_enabled: true)
   end
   after_action :expire_etag_cache, only: [:cancel_auto_stop]
 

app/services/environments/auto_stop_service.rb

@@ -30,7 +30,7 @@ module Environments
     def stop_in_batch
       environments = Environment.auto_stoppable(BATCH_SIZE)
 
-      return false unless environments.exists? && Feature.enabled?(:auto_stop_environments)
+      return false unless environments.exists? && Feature.enabled?(:auto_stop_environments, default_enabled: true)
 
       Ci::StopEnvironmentsService.execute_in_batch(environments)
     end

app/workers/environments/auto_stop_cron_worker.rb

@@ -8,7 +8,7 @@ module Environments
     feature_category :continuous_delivery
 
     def perform
-      return unless Feature.enabled?(:auto_stop_environments)
+      return unless Feature.enabled?(:auto_stop_environments, default_enabled: true)
 
       AutoStopService.new.execute
     end

doc/ci/environments.md

@@ -624,6 +624,73 @@ to automatically stop.
 
 You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop).
 
+#### Environments auto-stop
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20956) in GitLab 12.8.
+
+You can set a expiry time to environments and stop them automatically after a certain period.
+
+For example, consider the use of this feature with Review Apps environments.
+When you set up Review Apps, sometimes they keep running for a long time
+because some merge requests are left as open. An example for this situation is when the author of the merge
+request is not actively working on it, due to priority changes or a different approach was decided on, and the merge requests was simply forgotten.
+Idle environments waste resources, therefore they
+should be terminated as soon as possible.
+
+To address this problem, you can specify an optional expiration date for
+Review Apps environments. When the expiry time is reached, GitLab will automatically trigger a job
+to stop the environment, eliminating the need of manually doing so. In case an environment is updated, the expiration is renewed
+ensuring that only active merge requests keep running Review Apps.
+
+To enable this feature, you need to specify the [`environment:auto_stop_in`](yaml/README.md#environmentauto_stop_in) keyword in `.gitlab-ci.yml`.
+You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`.
+`auto_stop_in` uses the same format of [`artifacts:expire_in` docs](yaml/README.md#artifactsexpire_in).
+
+##### Auto-stop example
+
+In the following example, there is a basic review app setup that creates a new environment
+per merge request. The `review_app` job is triggered by every push and
+creates or updates an environment named `review/your-branch-name`.
+The environment keeps running until `stop_review_app` is executed:
+
+```yaml
+review_app:
+  script: deploy-review-app
+  environment:
+    name: review/$CI_COMMIT_REF_NAME
+    on_stop: stop_review_app
+    auto_stop_in: 1 week
+
+stop_review_app:
+  script: stop-review-app
+  environment:
+    name: review/$CI_COMMIT_REF_NAME
+    action: stop
+  when: manual
+```
+
+As long as a merge request is active and keeps getting new commits,
+the review app will not stop, so developers don't need to worry about
+re-initiating review app.
+
+On the other hand, since `stop_review_app` is set to `auto_stop_in: 1 week`,
+if a merge request becomes inactive for more than a week,
+GitLab automatically triggers the `stop_review_app` job to stop the environment.
+
+You can also check the expiration date of environments through the GitLab UI. To do so,
+go to **Operations > Environments > Environment**. You can see the auto-stop period
+at the left-top section and a pin-mark button at the right-top section. This pin-mark
+button can be used to prevent auto-stopping the environment. By clicking this button, the `auto_stop_in` setting is over-written
+and the environment will be active until it's stopped manually.
+
+![Environment auto stop](img/environment_auto_stop_v12_8.png)
+
+NOTE: **NOTE**
+Due to the resource limitation, a background worker for stopping environments only
+runs once every hour. This means environments will not be stopped at the exact
+timestamp as the specified period, but will be stopped when the hourly cron worker
+detects expired environments.
+
 ### Grouping similar environments
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.

doc/ci/review_apps/index.md

@@ -80,6 +80,11 @@ you can copy and paste into `.gitlab-ci.yml` as a starting point. To do so:
 
 1. Feel free to tune this template to your own needs.
 
+## Review Apps auto-stop
+
+See how to [configure Review Apps environments to expire and auto-stop](../environments.md#environments-auto-stop)
+after a given period of time.
+
 ## Review Apps examples
 
 The following are example projects that demonstrate Review App configuration:

doc/ci/yaml/README.md

@@ -105,7 +105,7 @@ The following table lists available parameters for jobs:
 | [`tags`](#tags)                                    | List of tags which are used to select Runner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | [`allow_failure`](#allow_failure)                  | Allow job to fail. Failed job doesn't contribute to commit status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | [`when`](#when)                                    | When to run job. Also available: `when:manual` and `when:delayed`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| [`environment`](#environment)                      | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, and `environment:action`.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`environment`](#environment)                      | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in` and `environment:action`.                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | [`cache`](#cache)                                  | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, and `cache:policy`.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [`artifacts`](#artifacts)                          | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`, and `artifacts:reports:junit`.<br><br>In GitLab [Enterprise Edition](https://about.gitlab.com/pricing/), these are available: `artifacts:reports:codequality`, `artifacts:reports:sast`, `artifacts:reports:dependency_scanning`, `artifacts:reports:container_scanning`, `artifacts:reports:dast`, `artifacts:reports:license_management`, `artifacts:reports:performance` and `artifacts:reports:metrics`. |
 | [`dependencies`](#dependencies)                    | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -1453,6 +1453,29 @@ The `stop_review_app` job is **required** to have the following keywords defined
 - `stage` should be the same as the `review_app` in order for the environment
   to stop automatically when the branch is deleted
 
+#### `environment:auto_stop_in`
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20956) in GitLab 12.8.
+
+The `auto_stop_in` keyword is for specifying life period of the environment,
+that when expired, GitLab GitLab automatically stops them.
+
+For example,
+
+```yaml
+review_app:
+  script: deploy-review-app
+  environment:
+    name: review/$CI_COMMIT_REF_NAME
+    auto_stop_in: 1 day
+```
+
+When `review_app` job is executed and a review app is created, a life period of
+the environment is set to `1 day`.
+
+For more information, see
+[the environments auto-stop documentation](../environments.md#environments-auto-stop)
+
 #### `environment:kubernetes`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27630) in GitLab 12.6.