This is an automated email from the ASF dual-hosted git repository.
pcongiusti pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit b0a0af7bcbb904187951a26c9f3fea2aa20bcce0
Author: Pasquale Congiusti <pasquale.congiu...@gmail.com>
AuthorDate: Wed Jun 21 10:33:22 2023 +0200
doc: tekton cicd
---
docs/modules/ROOT/nav.adoc | 5 +-
docs/modules/ROOT/pages/pipeline/tekton.adoc | 60 ++++++
.../ROOT/pages/tutorials/tekton/tekton.adoc | 236 ---------------------
docs/modules/ROOT/pages/tutorials/tutorials.adoc | 8 -
4 files changed, 63 insertions(+), 246 deletions(-)
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index ff74541c5..e01203e34 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -35,7 +35,6 @@
** xref:running/local.adoc[Run Locally]
** xref:running/promoting.adoc[Promote an Integration]
** xref:running/knative-sink.adoc[Knative Sinks]
-** xref:tutorials/tutorials.adoc[Examples]
* xref:configuration/configuration.adoc[Configuration]
** xref:configuration/build-time-properties.adoc[Build time properties]
** xref:configuration/components.adoc[Components]
@@ -43,7 +42,9 @@
** xref:configuration/runtime-properties.adoc[Properties]
** xref:configuration/runtime-config.adoc[Runtime configuration]
** xref:configuration/runtime-resources.adoc[Runtime resources]
-* xref:pipeline/pipeline.adoc[Pipeline]
+* Pipelines
+* xref:pipeline/pipeline.adoc[Basic]
+* xref:pipeline/tekton.adoc[Tekton]
* Observability
** xref:observability/logging.adoc[Logging]
*** xref:observability/logging/operator.adoc[Operator]
diff --git a/docs/modules/ROOT/pages/pipeline/tekton.adoc
b/docs/modules/ROOT/pages/pipeline/tekton.adoc
new file mode 100644
index 000000000..cd62fc3f9
--- /dev/null
+++ b/docs/modules/ROOT/pages/pipeline/tekton.adoc
@@ -0,0 +1,60 @@
+[[full-fledged-pipeline]]
+= Full fledged Pipeline
+
+If you're running a production grade enterprise system, you likely want to use
a full fledged CICD technology. The basic features provided by our
xref:pipeline/pipeline.adoc[homemade Pipeline] may be definetely limited in
such situation. For those production grade requirements we suggest to integrate
one of the many CICD technologies around. One that we want to suggest and for
which we provide an opinionated approach is https://tekton.dev/[Tekton CICD].
+
+[[tekton-pipeline]]
+== Integrate with Tekton
+
+In Camel K version 2 we are supporting a Task which we're willing to include
in https://hub.tekton.dev/[Tekton Hub]. Here it follows the instructions and
some example to show you how to adopt this technology togheter with Camel K.
The prerequisite is to have Camel K and Tekton operators up and running. This
brief guide requires certain previous familiarity with Tekton technology as
well.
+
+=== Install the Task
+
+```shell
+kubectl apply -f
https://raw.githubusercontent.com/apache/camel-k/main/tekton/kamel-run/0.1/kamel-run.yaml
+```
+=== Parameters
+
+- **camel-k-image**: The name of the image containing the Kamel CLI
(_default:_ docker.io/apache/camel-k:1.12.0).
+- **filename**: the file containing the Integration source.
+- **namespace**: the namespace where to run the Integration (_default:_ the
task execution namespace).
+- **container-image**: the container image to use for this Integration. Useful
when you want to build your own container for the Integration (_default:_
empty, will trigger an Integration build).
+- **wait**: wait for the Integration to run before finishing the task. Useful
when you want to get the **integration-phase** result (_default:_ "false").
+
+=== Workspaces
+
+* **source**: A
https://github.com/tektoncd/pipeline/blob/main/docs/workspaces.md[Workspace]
containing the Integration source to run.
+
+=== Results
+
+- **integration-name**: the Integration name which was created/updated.
+- **integration-phase**: the status of the Integration, tipycally used with
**wait: true** input parameter.
+
+=== Platforms
+
+The Task can be run on `linux/amd64` platform.
+
+=== Usage
+
+The Task can be used in several ways to accomodate the different build and
deployment strategy you may have.
+
+=== Create the Service Account
+
+As we will do delegate the task, the creation of an Integration, we need to
provide a `ServiceAccount` with the privileges required by the tasks:
+
+```shell
+kubectl apply -f
https://raw.githubusercontent.com/apache/camel-k/main/tekton/kamel-run/0.1/support/camel-k-tekton.yaml
+```
+
+[[tekton-pipeline-examples]]
+== Examples
+
+Here some examples that may resylt useful for your use case.
+
+=== Delegate build to operator
+
+Use the
https://raw.githubusercontent.com/apache/camel-k/main/tekton/kamel-run/0.1/samples/run-operator-build.yaml[Tekton
Camel K operator builder sample] in order to fetch a Git repository and run a
Camel K Integration delegating the build to the Camel K operator.
+
+=== Full pipeline with custom build
+
+Use the
https://raw.githubusercontent.com/apache/camel-k/main/tekton/kamel-run/0.1/samples/run-external-build.yaml[Tekton
Camel K external builder sample] as a reference for a full pipeline where you
define your own process of building the Camel application and using the
`kamel-run` Task as last step in order to deploy the Integration and let Camel
K operator managing it.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/tutorials/tekton/tekton.adoc
b/docs/modules/ROOT/pages/tutorials/tekton/tekton.adoc
deleted file mode 100644
index 31f520a09..000000000
--- a/docs/modules/ROOT/pages/tutorials/tekton/tekton.adoc
+++ /dev/null
@@ -1,236 +0,0 @@
-[[tutorials-tekton]]
-= Camel K in Tekton Pipelines
-
-[[tutorials-tekton-introduction]]
-== Introduction
-
-NOTE: Available from Camel K 1.8.0
-
-Camel K can be directly used in https://github.com/tektoncd/pipeline[Tekton
Pipelines] tasks since it's container image ships the `kamel` CLI tool, that
-can be used to create all needed resources by interacting with the Kubernetes
cluster.
-
-For example, the following Tekton pipeline task can be used to run an
integration:
-
-[#camel-k-task-run-integration]
-[source,yaml]
-----
-apiVersion: tekton.dev/v1alpha1
-kind: Task
-metadata:
- name: camel-k-run-integration
-spec:
- inputs:
- resources:
- - name: repository
- type: git
- params:
- - name: file
- description: The integration file to run
- steps:
- - name: run-integration
- image: docker.io/apache/camel-k:1.8.0 //<1>
- workingDir: /workspace/repository
- command:
- - kamel
- args:
- - "run"
- - "--wait"
- - "$(inputs.params.file)" //<2>
-----
-
-
-<1> The base image for the step is `apache/camel-k:1.8.0`
-<2> It executes command `kamel run --wait ${inputs.params.file}`, with file to
run received as parameter
-
-When executed, such task creates an integration resource from the given file
(which is supposed to be contained in the input git repository) and waits for
the integration to be fully running before completing.
-
-This task is a building block for more complex scenarios that can be composed
in Tekton pipelines.
-If you want to learn more, just follow the remainder of the tutorial.
-
-[[tutorials-tekton-prerequisites]]
-== Prerequisites
-
-This tutorial assumes the following requirements are met:
-
-* OpenShift (or OKD) 4+ cluster (works also on "vanilla" Kubernetes with some
adjustment) and `oc` binary tool
-* Tekton Pipelines 0.5.2 (different versions may need adjustments)
-* Camel K Client Tools 1.0.0-M2 (`kamel` binary tool)
-
-[[tutorials-tekton-cluster-setup]]
-== Cluster Setup
-
-This tutorial assumes that **Tekton Pipelines are already installed** in the
cluster. Refer to the https://github.com/tektoncd/pipeline[Tekton documentation]
-to learn how to install them.
-
-Camel K cluster resources need to be installed on the cluster:
-
-[source,bash]
-----
-# Use the oc tool to login as cluster admin to the target cluster, then
-kamel install --cluster-setup
-----
-
-This will install the Camel K CRD (custom resource definitions) and roles to
access them.
-You can switch to a standard user after doing this operation.
-
-[[tutorials-tekton-creating-the-pipeline]]
-== Creating the Pipeline
-
-We're going to create a pipeline on a new namespace. The first step is to
create the namespace:
-
-[source,bash]
-----
-oc new-project camel-pipelines
-----
-
-=== Setting up a ServiceAccount
-
-Any running container that needs to interact with the Kubernetes API (in our
case, to create deployment and integration resources) must
-have special permissions granted to its service account.
-
-Download the
xref:attachment$tekton/camel-k-pipeline-permissions.yaml[camel-k-pipeline-permissions.yaml]
file and save it into a directory in your hard drive.
-Then install it using the `oc` client tool:
-
-[source,bash]
-----
-oc apply -f camel-k-pipeline-permissions.yaml
-----
-
-This creates a
https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/[Kubernetes
ServiceAccount] named `camel-k-pipeline`
-that is authorized to create the same kind of resources that the Camel K
operator needs to create. We'll use that service account to run our pipeline.
-
-=== Creating the Pipeline Definition
-
-Let's now create the pipeline definition. Download the
xref:attachment$tekton/camel-k-pipeline-task-definition.yaml[camel-k-pipeline-task-definition.yaml]
file
-and apply it to the cluster:
-
-[source,bash]
-----
-oc apply -f camel-k-pipeline-task-definition.yaml
-----
-
-This creates a series of resources, including a pipeline definition that you
can immediately see on the OpenShift developer console.
-
-image::tekton/tekton-pipeline-definition.png[View of the Camel K Tekton
pipeline in the OpenShift developer console]
-
-The pipeline just created is composed of two tasks.
-
-The last task (`camel-k-run-integration`) is the one we've
<<camel-k-task-run-integration,already described in the introduction>>, while
the first task just installs the operator in the current namespace.
-The definition of the first task is shown in the following excerpt:
-
-[source,yaml]
-----
-apiVersion: tekton.dev/v1alpha1
-kind: Task
-metadata:
- name: camel-k-install-operator
-spec:
- steps:
- - name: install
- image: docker.io/apache/camel-k:1.8.0
- command:
- - kamel
- args:
- - "install"
- - "--skip-cluster-setup"
-----
-
-As you see, it's just doing a `kamel install --skip-cluster-setup` (we've
already done the cluster setup in the
<<tutorials-tekton-cluster-setup,preparation phase>>).
-
-
-Both tasks are executed in sequence in the pipeline that is shown below.
-
-[source,yaml]
-----
-apiVersion: tekton.dev/v1alpha1
-kind: Pipeline
-metadata:
- name: camel-k-pipeline
-spec:
- resources:
- - name: source-repo
- type: git
- tasks:
- - name: install-operator
- taskRef:
- name: camel-k-install-operator
- - name: run-integration
- runAfter: [install-operator]
- taskRef:
- name: camel-k-run-integration
- resources:
- inputs:
- - name: repository
- resource: source-repo
- params:
- - name: file
- value: "examples/tekton/hello.groovy"
-----
-
-The integration file to be executed is set to `examples/tekton/hello.groovy`
that is a simple "Hello World" integration contained in the Camel K
-github repository
https://github.com/apache/camel-k/tree/main/example/tekton[example/tekton
directory].
-
-In order to specify the actual source repository, the definition file contains
also the following resource:
-
-[source,yaml]
-----
-apiVersion: tekton.dev/v1alpha1
-kind: PipelineResource
-metadata:
- name: camel-k-examples-git
-spec:
- type: git
- params:
- - name: revision
- value: main
- - name: url
- value: https://github.com/apache/camel-k
-----
-
-The repo will be now used as input for the
<<camel-k-task-run-integration,run-integration task>> in the pipeline.
-
-=== Triggering a Pipeline Execution
-
-Everything is now ready to be executed and the last thing missing is a
trigger. Download the
xref:attachment$tekton/camel-k-pipeline-task-run.yaml[camel-k-pipeline-task-run.yaml]
file
-and apply it to the cluster:
-
-[source,bash]
-----
-oc apply -f camel-k-pipeline-task-run.yaml
-----
-
-The file contains only a PipelineRun resource:
-
-[source,yaml]
-----
-apiVersion: tekton.dev/v1alpha1
-kind: PipelineRun
-metadata:
- name: camel-k-pipeline-run-1
-spec:
- pipelineRef:
- name: camel-k-pipeline
- serviceAccount: 'camel-k-pipeline' //<1>
- resources:
- - name: source-repo
- resourceRef:
- name: camel-k-examples-git //<2>
-----
-
-<1> The PipelineRun binds the pipeline to the service account previously
created
-<2> It also binds the pipeline to the Camel K repository containing the
examples
-
-The creation of the file starts the execution of the pipeline and its progress
can be monitored on the OpenShift developer console.
-
-image::tekton/tekton-pipeline-run.png[View of the Camel K Tekton pipeline
execution in the OpenShift developer console]
-
-CAUTION: To execute the PipelineRun again, delete previous runs before
re-applying
-
-The result of the pipeline execution is the Camel K operator and an
integration named `hello` running on the cluster:
-
-image::tekton/tekton-pipeline-result.png[Result of the Camel K Tekton pipeline
execution]
-
-There are certainly other ways to trigger an execution of a pipeline, like as
reaction to a change in the git repository,
-but this is left to you as exercise ;)
-
-Refer to the https://github.com/tektoncd/pipeline[Tekton repository] for more
information.
diff --git a/docs/modules/ROOT/pages/tutorials/tutorials.adoc
b/docs/modules/ROOT/pages/tutorials/tutorials.adoc
deleted file mode 100644
index 935fb152e..000000000
--- a/docs/modules/ROOT/pages/tutorials/tutorials.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[tutorials]]
-= Camel K Tutorials
-
-The
https://github.com/apache/camel-k-examples/tree/main/generic-examples[apache/camel-k-examples]
repository contains a curated collection of
-tutorials that drives you from the basics of Camel K to more advanced features.
-
-NOTE: The xref:tutorials/tekton/tekton.adoc[Tekton Pipelines] example is still
available here and it's going to be migrated to
-the
https://github.com/apache/camel-k/tree/main/examples[apache/camel-k-examples]
repository.
