Initial push of runner resource

Author: RicePatrick

docs/resources/runner.md

@@ -3,69 +3,104 @@
 page_title: "gitlab_runner Resource - terraform-provider-gitlab"
 subcategory: ""
 description: |-
-  The gitlab_runner resource allows registering a runner, either at an instance level
-  or at a group level. The runner will be registered at a group level if the token used is from a group, or at an
-  instance level if the token used is for the instance.
+  The gitlab_runner resource allows to manage the lifecycle of a runner.
+  A runner can either be registered at an instance level or group level.
+  The runner will be registered at a group level if the token used is from a group, or at an instance level if the token used is for the instance.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner
 ---
 
 # gitlab_runner (Resource)
 
-The `gitlab_runner` resource allows registering a runner, either at an instance level
-or at a group level. The runner will be registered at a group level if the token used is from a group, or at an 
-instance level if the token used is for the instance.
+The `gitlab_runner` resource allows to manage the lifecycle of a runner.
+		
+A runner can either be registered at an instance level or group level. 
+The runner will be registered at a group level if the token used is from a group, or at an instance level if the token used is for the instance.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner)
 
 ## Example Usage
 
 ```terraform
-# Basic GitLab Runner
-resource "gitlab_runner" "this" {
-  token = "12345"
+# Basic GitLab Group Runner
+resource "gitlab_group" "my_group" {
+  name        = "my runner"
+  description = "group that holds the runners"
+}
+resource "gitlab_runner" "basic_runner" {
+  registration_token = gitlab_group.my_group.runners_token
 }
 
 # GitLab Runner that runs only tagged jobs
 resource "gitlab_runner" "tagged_only" {
-  token       = "12345"
-  description = "I only run tagged jobs"
+  registration_token = gitlab_group.my_group.runners_token
+  description        = "I only run tagged jobs"
 
   run_untagged = "false"
   tag_list     = ["tag_one", "tag_two"]
 }
 
 # GitLab Runner that only runs on protected branches
 resource "gitlab_runner" "protected" {
-  token       = "12345"
-  description = "I only run protected jobs"
+  registration_token = gitlab_group.my_group.runners_token
+  description        = "I only run protected jobs"
 
   access_level = "ref_protected"
 }
+
+# Generate a `config.toml` file that you can use to create a runner
+# This is the typical workflow for this resource, using it to create an authentication_token which can then be used
+# to generate the `config.toml` file to prevent re-registering the runner every time new hardware is created.
+
+resource "gitlab_group" "my_custom_group" {
+  name        = "my custom runner"
+  description = "group that holds the custom runners"
+}
+
+resource "gitlab_runner" "my_runner" {
+  registration_token = gitlab_group.my_custom_group.runners_token
+}
+
+# This creates a configuration for a local "shell" runner, but can be changed to generate whatever is needed.
+# Place this configuration file on a server at `/etc/gitlab-runner/config.toml`, then run `gitlab-runner start`.
+# See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for more information.
+resource "local_file" "config" {
+  filename = "${path.module}/config.toml"
+  content  = <<CONTENT
+  concurrent = 1
+
+  [[runners]]
+    name = "Hello Terraform"
+    url = "https://example.gitlab.com/"
+    token = "${gitlab_runner.my_runner.authentication_token}"
+    executor = "shell"
+    
+  CONTENT
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `token` (String, Sensitive) The registration token used to register the runner
+- `registration_token` (String, Sensitive) The registration token used to register the runner.
 
 ### Optional
 
-- `access_level` (String) The access_level of the runner. Valid values are: `not_protected`, `ref_protected`
-- `description` (String) The runner's description'
+- `access_level` (String) The access_level of the runner. Valid values are: `not_protected`, `ref_protected`.
+- `description` (String) The runner's description.
 - `id` (String) The ID of this resource.
-- `locked` (Boolean) Whether the runner should be locked for current project
-- `maximum_timeout` (Number) Maximum timeout set when this runner handles the job
-- `paused` (Boolean) Whether the runner should ignore new jobs
-- `run_untagged` (Boolean) Whether the runner should handle untagged jobs
-- `tag_list` (List of String) List of runner’s tags
+- `locked` (Boolean) Whether the runner should be locked for current project.
+- `maximum_timeout` (Number) Maximum timeout set when this runner handles the job.
+- `paused` (Boolean) Whether the runner should ignore new jobs.
+- `run_untagged` (Boolean) Whether the runner should handle untagged jobs.
+- `tag_list` (List of String) List of runner’s tags.
 
 ### Read-Only
 
 - `authentication_token` (String, Sensitive) The authentication token used for building a config.toml file. This value is not present when imported.
 - `status` (String) The status of runners to show, one of: online and offline. active and paused are also possible values
-				 which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
+				              which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0.
 
 ## Import
 

examples/resources/gitlab_runner/resource.tf

@@ -1,21 +1,56 @@
-# Basic GitLab Runner
-resource "gitlab_runner" "this" {
-  token = "12345"
+# Basic GitLab Group Runner
+resource "gitlab_group" "my_group" {
+  name        = "my runner"
+  description = "group that holds the runners"
+}
+resource "gitlab_runner" "basic_runner" {
+  registration_token = gitlab_group.my_group.runners_token
 }
 
 # GitLab Runner that runs only tagged jobs
 resource "gitlab_runner" "tagged_only" {
-  token       = "12345"
-  description = "I only run tagged jobs"
+  registration_token = gitlab_group.my_group.runners_token
+  description        = "I only run tagged jobs"
 
   run_untagged = "false"
   tag_list     = ["tag_one", "tag_two"]
 }
 
 # GitLab Runner that only runs on protected branches
 resource "gitlab_runner" "protected" {
-  token       = "12345"
-  description = "I only run protected jobs"
+  registration_token = gitlab_group.my_group.runners_token
+  description        = "I only run protected jobs"
 
   access_level = "ref_protected"
-}
+}
+
+# Generate a `config.toml` file that you can use to create a runner
+# This is the typical workflow for this resource, using it to create an authentication_token which can then be used
+# to generate the `config.toml` file to prevent re-registering the runner every time new hardware is created.
+
+resource "gitlab_group" "my_custom_group" {
+  name        = "my custom runner"
+  description = "group that holds the custom runners"
+}
+
+resource "gitlab_runner" "my_runner" {
+  registration_token = gitlab_group.my_custom_group.runners_token
+}
+
+# This creates a configuration for a local "shell" runner, but can be changed to generate whatever is needed.
+# Place this configuration file on a server at `/etc/gitlab-runner/config.toml`, then run `gitlab-runner start`.
+# See https://docs.gitlab.com/runner/configuration/advanced-configuration.html for more information.
+resource "local_file" "config" {
+  filename = "${path.module}/config.toml"
+  content  = <<CONTENT
+  concurrent = 1
+
+  [[runners]]
+    name = "Hello Terraform"
+    url = "https://example.gitlab.com/"
+    token = "${gitlab_runner.my_runner.authentication_token}"
+    executor = "shell"
+    
+  CONTENT
+}
+