forked from pivotal/docs-tap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgetting-started.md.hbs
1504 lines (1087 loc) · 64.9 KB
/
getting-started.md.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Getting started with the Tanzu Application Platform
## <a id="purpose"></a>Purpose
Welcome to the Tanzu Application Platform. This document guides you through getting started on the platform. Specifically, you are going to learn how to:
- Develop and promote an application
- Create an application accelerator
- Add testing and security scanning to an application
- Administer, set up, and manage supply chains
Before getting started, you must complete the prerequisites in the next section.
## <a id="get-started-prereqs"></a>Getting started prerequisites
Verify you have successfully:
- **Installed the Tanzu Application Platform**<br>
See [Installing Tanzu Application Platform](install-intro.md).
- **Installed the Tanzu Application Platform on the target Kubernetes cluster**<br>
See [Installing the Tanzu CLI](install-tanzu-cli.md) and [Installing the Tanzu Application Platform Package and Profiles](install.md).
- **Set the default kubeconfig context to the target Kubernetes cluster**<br>
See [Changing clusters](cli-plugins/apps/usage.md#changing-clusters).
- **Installed Out of The Box (OOTB) Supply Chain Basic**<br>
See [Install Out of The Box Supply Chain Basic](scc/install-ootb-sc-basic.md).
>**Note:** If you used the default profiles provided in [Installing the Tanzu Application Platform Package and Profiles](install.md),
you have already installed the Out of The Box (OOTB) Supply Chain Basic.
- **Installed Tekton-Pipelines**<br>
See [Install Tekton Pipelines](install-components.md#install-tekton-pipelines).
>**Note:** If you used the default profiles provided in [Installing the Tanzu Application Platform Package and Profiles](install.md),
you have already installed Tekton Pipelines.
- **Set up a developer namespace to accommodate the developer Workload**<br>
See [Set up developer namespaces to use installed packages](install-components.md#setup).
- **Installed Tanzu Application Platform GUI**<br>
See [Install Tanzu Application Platform GUI](install-components.md#install-tap-gui).
- **Installed the VSCode Tanzu Extension**<br>
See [Install the Visual Studio Code Tanzu Extension](vscode-extension/installation.md) for instructions.
When you have completed the prerequisites, you are ready to get started.
## <a id="dev-first-app"></a>Section 1: Develop your first application on the Tanzu Application Platform
In this section, you are going to:
- Learn about application accelerators
- Deploy your application
- Add your application to Tanzu Application Platform GUI Software Catalog
- Set up your integrated development environment (IDE)
- Iterate on your application
- Live update your application
- Debug your application
- Monitor your running application
### <a id="about-app-accs"></a>About application accelerators
Application accelerators are templates that not only codify best practices, but also provide important configuration and structures ready and available for use. Developers can create applications and get started with feature development immediately. Admins can create custom application accelerators that reflect desired architectures and configurations, enabling developer use according to the best practices defined. The Application Accelerator plug-in of Tanzu Application Platform GUI assists both application developers and admins with creating and generating application accelerators. To create your own application accelerator, see [Create your accelerator](#create-app-acc).
### <a id="deploy-your-app"></a>Deploy your application
To deploy your application, you must download an accelerator, upload it on your Git repository of choice, and run a CLI command. VMware recommends using the accelerator called `Tanzu-Java-Web-App`.
1. From Tanzu Application Platform GUI portal, click **Create** located on the left-hand side of the
navigation bar to see the list of available accelerators.
For information about connecting to Tanzu Application Platform GUI, see
[Accessing Tanzu Application Platform GUI](tap-gui/accessing-tap-gui.md).
2. Locate the Tanzu Java Web App accelerator, which is a Spring Boot web app, and click **CHOOSE**.
3. In the **Generate Accelerators** dialog box, replace the default value `dev.local` in the **prefix for container image registry** field
with the registry in the form of `SERVER-NAME/REPO-NAME`.
The `SERVER-NAME/REPO-NAME` must match what was specified for `registry` as part of the installation values for `ootb_supply_chain_basic`.
Click **NEXT STEP**, verify the provided information, and click **CREATE**.
4. After the Task Activity processes complete, click **DOWNLOAD ZIP FILE**.
5. After downloading the ZIP file, expand it in a workspace directory and follow your preferred procedure for uploading the generated project files to a Git repository for your new project.
6. Ensure you have [set up developer namespaces to use installed packages](install-components.md#setup).
7. Deploy the Tanzu Java Web App accelerator by running the `tanzu apps workload create` command:
```console
tanzu apps workload create tanzu-java-web-app \
--git-repo GIT-URL-TO-PROJECT-REPO \
--git-branch main \
--type web \
--label app.kubernetes.io/part-of=tanzu-java-web-app \
--yes \
--namespace YOUR-DEVELOPER-NAMESPACE
```
Where `GIT-URL-TO-PROJECT-REPO` is the path you uploaded to in step 5 and `YOUR-DEVELOPER-NAMESPACE` is the namespace configured in step 6.
If you bypassed step 5 or were unable to upload your accelerator to a Git repository, use the following public version to test:
```console
tanzu apps workload create tanzu-java-web-app \
--git-repo https://github.com/sample-accelerators/tanzu-java-web-app \
--git-branch main \
--type web \
--label app.kubernetes.io/part-of=tanzu-java-web-app \
--yes \
--namespace YOUR-DEVELOPER-NAMESPACE
```
Where `YOUR-DEVELOPER-NAMESPACE` is the namespace configured in step 6.
For more information, see [Tanzu Apps Workload Create](cli-plugins/apps/command-reference/tanzu-apps-workload-create.md).
> **Note:** This deployment uses an accelerator source from Git, but in later steps you use the VSCode extension
to debug and live-update this application.
8. View the build and runtime logs for your app by running the `tail` command:
```console
tanzu apps workload tail tanzu-java-web-app --since 10m --timestamp --namespace YOUR-DEVELOPER-NAMESPACE
```
Where `YOUR-DEVELOPER-NAMESPACE` is the namespace configured in step 6.
9. After the workload is built and running, you can view the Web App in your browser. View the URL of the Web App by running the command below, and then press **ctrl-click** on the
Workload Knative Services URL at the bottom of the command output.
```console
tanzu apps workload get tanzu-java-web-app --namespace YOUR-DEVELOPER-NAMESPACE
```
Where `YOUR-DEVELOPER-NAMESPACE` is the namespace configured in step 6.
### <a id="add-app-to-gui-cat"></a>Add your application to Tanzu Application Platform GUI Software Catalog
1. Navigate to the home page of Tanzu Application Platform GUI and click **Home**, located on the left-side navigation bar.
Click **REGISTER ENTITY**.
Alternatively, you can add a link to the `catalog-info.yaml` to the `tap-values.yaml` configuration file in the `tap_gui.app_config.catalog.locations` section. See [Installing the Tanzu Application Platform Package and Profiles](install.md#a-idfull-profilea-full-profile).
1. **Register an existing component** prompts you to type a repository URL.
Type the link to the `catalog-info.yaml` file of the tanzu-java-web-app in the Git repository field, for example,
`https://github.com/USERNAME/PROJECTNAME/blob/main/catalog-info.yaml`.
1. Click **ANALYZE**.
1. Review the catalog entities to be added and click **IMPORT**.
1. Navigate back to the home page. The catalog changes and entries are visible for further inspection.
>**Note:** If your Tanzu Application Platform GUI instance does not have a [PostgreSQL](tap-gui/database.md) database configured, the `catalog-info.yaml` location must be re-registered after the instance is restarted or upgraded.
### <a id="iterate"></a>Iterate on your application
Now that you have a skeleton workload working, you are ready to iterate on your application
and test code changes on the cluster.
Tanzu Developer Tools for Visual Studio Code, VMware Tanzu’s official IDE extension for VSCode,
helps you develop and receive fast feedback on your workloads running on the Tanzu Application Platform.
The VSCode extension enables live updates of your application while running on the cluster
and allows you to debug your application directly on the cluster.
For information about installing the prerequisites and the Tanzu Developer Tools extension, see
[Install Tanzu Dev Tools for VSCode](vscode-extension/installation.md).
>**Note:** Use Tilt v0.23.2 or a later version for the sample application.
1. Open the Tanzu Java Web App as a project within your VSCode IDE.
2. To ensure your extension assists you with iterating on the correct project, configure its settings using the following instructions.
- In Visual Studio Code, navigate to `Preferences` > `Settings` > `Extensions` > `Tanzu`.
- In the **Local Path** field, provide the path to the directory containing the Tanzu Java Web App. The current directory is the default.
- In the **Source Image** field, provide the destination image repository to publish an image containing your workload source code.
For example, `gcr.io/myteam/tanzu-java-web-app-source`.
You are now ready to iterate on your application.
### <a id="live-update-your-app"></a>Live update your application
Deploy the application to view it updating live on the cluster to demonstrate how code changes are going to behave on a production cluster early in the development process.
Follow the following steps to live update your application:
1. From the Command Palette (⇧⌘P), type in and select `Tanzu: Live Update Start`.
You can view output from Tanzu Application Platform and from Tilt indicating that the container is being built and deployed.
- You see "Live Update starting..." in the status bar at the bottom right.
- Live update can take 1 to 3 minutes while the workload deploys and the Knative service becomes available.
>**Note:** Depending on the type of cluster you use, you might see an error similar to the following:
>`ERROR: Stop! cluster-name might be production.
>If you're sure you want to deploy there, add:
>allow_k8s_contexts('cluster-name')
>to your Tiltfile. Otherwise, switch k8scontexts and restart Tilt.
`
>Follow the instructions and add the line `allow_k8s_contexts('cluster-name')` to your `Tiltfile`.
2. When the Live Update status in the status bar is visible, resolve to "Live Update Started", navigate to `http://localhost:8080` in your browser, and view your running application.
3. Enter to the IDE and make a change to the source code. For example, in `HelloController.java`, edit the string returned to say `Hello!` and save.
4. The container is updated when the logs stop streaming. Navigate to your browser and refresh the page.
5. View the changes to your workload running on the cluster.
6. Either continue making changes, or stop and deactivate the live update when finished. Open the command palette (⇧⌘P), type `Tanzu`, and choose an option.
### <a id="debug-your-app"></a>Debug your application
Debug your cluster either on the application or in your local environment.
Follow the following steps to debug your cluster:
1. Set a breakpoint in your code.
2. Right-click the file `workload.yaml` within the `config` directory, and select **Tanzu: Java Debug Start**. In a few moments, the workload is redeployed with debugging enabled. You are going to see the "Deploy and Connect" Task complete and the debug menu actions are available to you, indicating that the debugger has attached.
3. Navigate to `http://localhost:8080` in your browser. This hits the breakpoint within VSCode. Play to the end of the debug session using VSCode debugging controls.
### <a id="monitor-running-app"></a>Monitor your running application
Inspect the runtime characteristics of your running application using the Application Live View UI to monitor:
* Resource consumption
* Java Virtual Machine (JVM) status
* Incoming traffic
* Change log level
You can also troubleshoot environment variables and fine-tune the running application.
Follow the following steps to diagnose Spring Boot-based applications using Application Live View:
1. Confirm that the Application Live View components installed successfully. For instructions, see [Verify the Application Live View component](https://docs.vmware.com/en/Application-Live-View-for-VMware-Tanzu/1.2/docs/GUID-installing.html#verify-alv-connector-component).
1. Access the Application Live View Tanzu Application Platform GUI. For instructions, see [Entry point to Application Live View plug-in](tap-gui/plugins/app-live-view.html#plug-in-entry-point).
1. Select your running application to view the diagnostic options and inside the application. For more information, see [Product Features](https://docs.vmware.com/en/Application-Live-View-for-VMware-Tanzu/1.2/docs/GUID-product-features.html).
---
## <a id='create-app-acc'></a>Section 2: Create your application accelerator
In this section, you are going to create an application accelerator by using Tanzu Application Platform GUI and CLI.
### <a id="create-an-app-acc"></a>Create an application accelerator
You can use any Git repository to create an accelerator. You need the repository URL to create an accelerator.
The Git repository must be `public` and contain a `README.md` file. These options are available to configure when you create repositories on GitHub.
To create a new application accelerator by using your Git repository, follow these steps:
1. Clone your Git repository.
2. Create a file named `accelerator.yaml` in the root directory of this Git repository.
3. Add the following content to the `accelerator.yaml` file:
```yaml
accelerator:
displayName: Simple Accelerator
description: Contains just a README
iconUrl: https://images.freecreatives.com/wp-content/uploads/2015/05/smiley-559124_640.jpg
tags:
- simple
- getting-started
```
>**Note:** You can use any icon with a reachable URL.
4. Add the new `accelerator.yaml` file, commit this change and push to your Git repository.
## <a id="publish-accelerator"></a>Publish the new accelerator
To publish the new application accelerator that is created in your Git repository, follow these steps:
1. Run the following command to publish the new application accelerator:
```console
tanzu accelerator create simple --git-repository YOUR-GIT-REPOSITORY-URL --git-branch YOUR-GIT-BRANCH
```
Where:
- `YOUR-GIT-REPOSITORY-URL` is the URL of your Git repository.
- `YOUR-GIT-BRANCH` is the name of the branch where you pushed the new `accelerator.yaml` file.
2. Refresh Tanzu Application Platform GUI to reveal the newly published accelerator.
>**Note:** It might take a few seconds for Tanzu Application Platform GUI to refresh the catalog and add an entry for new accelerator.
## <a id="work-with-accelerators"></a>Working with accelerators
### <a id="accelerator-updates"></a>Updating an accelerator
After you push any changes to your Git repository, the Accelerator is refreshed based on the `git.interval` setting for the Accelerator resource. The default value is 10 minutes. You can run the following command to force an immediate reconciliation:
```console
tanzu accelerator update ACCELERATOR-NAME --reconcile
```
### <a id="accelerator-deletes"></a>Deleting an accelerator
When you no longer need your accelerator, you can delete it by using the Tanzu CLI:
```console
tanzu accelerator delete ACCELERATOR-NAME
```
### <a id="accelerator-manifest"></a>Using an accelerator manifest
You can also create a separate manifest file and apply it to the cluster by using the Tanzu CLI:
1. Create a `simple-manifest.yaml` file and add the following content:
```yaml
apiVersion: accelerator.apps.tanzu.vmware.com/v1alpha1
kind: Accelerator
metadata:
name: simple
namespace: accelerator-system
spec:
git:
url: YOUR-GIT-REPOSITORY-URL
ref:
branch: YOUR-GIT-BRANCH
```
Where:
- `YOUR-GIT-REPOSITORY-URL` is the URL of your Git repository.
- `YOUR-GIT-BRANCH` is the name of the branch.
1. Apply the `simple-manifest.yaml` by running the following command in the directory where you created this file:
```console
kubectl apply -f simple-manifest.yaml
```
---
## <a id="add-test-and-scan"></a> Section 3: Add Testing and Security Scanning to Your Application
In this section, you are going to:
- Learn about supply chains
- Discover available out of the box (OOTB) supply chains
- OOTB Basic (default)
- OOTB Testing
- OOTB Testing+Scanning
- Install OOTB Testing (optional)
- Install OOTB Testing+Scanning (optional)
### <a id="intro-supply-chain"></a>Introducing a Supply Chain
Supply Chains provide a way of codifying all of the steps of your path to production, more commonly known as continuous integration/Continuous Delivery (CI/CD). CI/CD is a method to frequently deliver applications by introducing automation into the stages of application development. The main concepts attributed to CI/CD are continuous integration, continuous delivery, and continuous deployment. CI/CD is the method used by supply chain to deliver applications through automation where supply chain allows you to use CI/CD and add any other steps necessary for an application to reach production, or a different environment such as staging.
### <a id="path-to-prod"></a>A path to production
A path to production allows users to create a unified access point for all of the tools required
for their applications to reach a customer-facing environment.
Instead of having four tools that are loosely coupled to each other, a path to production defines
all four tools in a single, unified layer of abstraction, which may be automated and repeatable between teams for applications at scale.
Where tools typically are not able to integrate with one another and additional scripting or
webhooks are necessary, there would be a unified automation tool to codify all the interactions
between each of the tools.
Supply chains used to codify the organization's path to production are configurable, allowing their
authors to add all of the steps of their application's path to production.
### <a id="avail-supply-chains"></a>Available Supply Chains
The Tanzu Application Platform provides three OOTB supply chains to
work with the Tanzu Application Platform components, and they include:
### <a id="OOTB-basic-sc-default"></a>1: **OOTB Basic (default)**
The default **OOTB Basic** supply chain and its dependencies were installed on your cluster during the Tanzu Application Platform install.
The following table and diagrams provide descriptions for each of the supply chains and dependencies provided with the Tanzu Application Platform.
<table>
<tr>
<td><strong>Name</strong>
</td>
<td><strong>Package Name</strong>
</td>
<td><strong>Description</strong>
</td>
<td><strong>Dependencies</strong>
</td>
</tr>
<tr>
<td><strong>Out of the Box Basic (Default - Installed during Installing Part 2)</strong>
</td>
<td><code>ootb-supply-chain-basic.tanzu.vmware.com</code>
</td>
<td>This supply chain monitors a repository that is identified in the developer’s `workload.yaml` file. When any new commits are made to the application, the supply chain:
<ul>
<li>Creates a new image.
<li>Applies any predefined conventions.
<li>Deploys the application to the cluster.
</li>
</ul>
</td>
<td>
<ul>
<li>Flux/Source Controller
<li>Tanzu Build Service
<li>Convention Service
<li>Tekton
<li>Cloud Native Runtimes
<li>If using Service References:
</li>
<ul>
<li>Service Bindings
<li>Services Toolkit
</li>
</ul>
</ul>
</td>
</tr>
</table>
### <a id="OOTB-testing"></a>2: **OOTB Testing**
The **OOTB Testing** supply chain runs a Tekton pipeline within the supply chain.
<table>
<tr>
<td><strong>Name</strong>
</td>
<td><strong>Package Name</strong>
</td>
<td><strong>Description</strong>
</td>
<td><strong>Dependencies</strong>
</td>
</tr>
<tr>
<td><strong>Out of the Box Testing</strong>
</td>
<td><code>ootb-supply-chain-testing.tanzu.vmware.com</code>
</td>
<td>The Out of the Box Testing contains all of the same elements as the Source to URL. It allows developers to specify a Tekton pipeline that runs as part of the CI step of the supply chain.
<ul>
<li>The application tests using the Tekton pipeline.
<li>A new image is created.
<li>Any predefined conventions are applied.
<li>The application is deployed to the cluster.
</li>
</ul>
</td>
<td>All of the Source to URL dependencies
<ul>
</ul>
</td>
</tr>
</table>
### <a id="OOTB-test-and-scan"></a>3: **OOTB Testing+Scanning**
The **OOTB Testing+Scanning** supply chain includes integrations for secure scanning tools.
<table>
<tr>
<td><strong>Name</strong>
</td>
<td><strong>Package Name</strong>
</td>
<td><strong>Description</strong>
</td>
<td><strong>Dependencies</strong>
</td>
</tr>
<tr>
<td><strong>Out of the Box Testing and Scanning</strong>
</td>
<td><code>ootb-supply-chain-testing-scanning.tanzu.vmware.com</code>
</td>
<td>The Out of the Box Testing and Scanning contains all of the same elements as the Out of the Box Testing supply chains but it also includes integrations out of the box with the secure scanning components of Tanzu Application Platform.
<ul>
<li>The application is tested using the provided Tekton pipeline.
<li>The application source code is scanned for vulnerabilities.
<li>A new image is created.
<li>The image is scanned for vulnerabilities.
<li>Any predefined conventions are applied.
<li>The application deploys to the cluster.
</li>
</ul>
</td>
<td>All of the Source to URL dependencies, and:
<ul>
<li>The secure scanning components included with Tanzu Application Platform
</li>
</ul>
</td>
</tr>
</table>
### <a id="install-ootb-test"></a>Install OOTB Testing
This section introduces how to install the OOTB Testing supply chain and
provides a sample Tekton pipeline that tests your sample application. The
pipeline is configurable. Therefore, you can customize the steps to perform
either additional testing or other tasks with Tekton Pipelines.
To apply this install method, follow the following steps:
1. You can activate the Out of the Box Supply Chain with Testing by updating our profile to use `testing` rather than `basic` as the selected supply chain for workloads in this cluster. Update `tap-values.yaml` (the file used to customize the profile in `Tanzu package install tap
--values-file=...`) with the following changes:
```yaml
- supply_chain: basic
+ supply_chain: testing
- ootb_supply_chain_basic:
+ ootb_supply_chain_testing:
registry:
server: "<SERVER-NAME>"
repository: "<REPO-NAME>"
```
2. Update the installed profile by running:
```console
tanzu package installed update tap -p tap.tanzu.vmware.com -v VERSION-NUMBER --values-file tap-values.yaml -n tap-install
```
Where `VERSION-NUMBER` is your Tanzu Application Platform version. For example, `{{ vars.tap_version }}`.
#### <a id="tekton-config-example"></a>Tekton pipeline config example
In this section, a Tekton pipeline is added to the cluster. In the next section,
the workload is updated to point to the pipeline and resolve any current errors.
To add the Tekton supply chain to the cluster, apply the following YAML to the cluster:
>**Note:** Developers can perform this step because they know how their application needs to be tested.
The operator can also add the Tekton supply chain to a cluster before the developer get access.
```yaml
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
name: developer-defined-tekton-pipeline
labels:
apps.tanzu.vmware.com/pipeline: test # (!) required
spec:
params:
- name: source-url # (!) required
- name: source-revision # (!) required
tasks:
- name: test
params:
- name: source-url
value: $(params.source-url)
- name: source-revision
value: $(params.source-revision)
taskSpec:
params:
- name: source-url
- name: source-revision
steps:
- name: test
image: gradle
script: |-
cd `mktemp -d`
wget -qO- $(params.source-url) | tar xvz -m
./mvnw test
```
The preceding YAML defines a Tekton Pipeline with a single step.
The step itself contained in the `steps` pull the code from the repository indicated
in the developers `workload` and run the tests within the repository.
The steps of the Tekton pipeline are configurable and allow the developer to add any additional items
that is needed to test their code.
Because this step is one of many in the supply chain (and the next step is an image build in this case),
the developer is free to focus on testing their code.
Any additional steps that the developer adds to the Tekton pipeline is independent
for the image being built and any subsequent steps of the supply chain being executed.
The `params` are templated by the Supply Chain Choreographer.
Additionally, Tekton pipelines require a Tekton `pipelineRun` in order to execute on the cluster.
The Supply Chain Choreographer handles creating the `pipelineRun` dynamically each time
that step of the supply requires execution.
#### <a id="test-workload-update"></a>Workload update
To connect the new supply chain to the workload,
the workload must be updated to point at your Tekton pipeline.
1. Update the workload by running the following with the Tanzu CLI:
```console
tanzu apps workload create tanzu-java-web-app \
--git-repo https://github.com/sample-accelerators/tanzu-java-web-app \
--git-branch main \
--type web \
--label apps.tanzu.vmware.com/has-tests=true \
--yes
```
```console
Create workload:
1 + |---
2 + |apiVersion: carto.run/v1alpha1
3 + |kind: Workload
4 + |metadata:
5 + | labels:
6 + | apps.tanzu.vmware.com/has-tests: "true"
7 + | apps.tanzu.vmware.com/workload-type: web
8 + | name: tanzu-java-web-app
9 + | namespace: default
10 + |spec:
11 + | source:
12 + | git:
13 + | ref:
14 + | branch: main
15 + | url: https://github.com/sample-accelerators/tanzu-java-web-app
? Do you want to create this workload? Yes
Created workload "tanzu-java-web-app"
```
2. After accepting the workload creation, monitor the creation of new resources by the workload by running:
```console
kubectl get workload,gitrepository,pipelinerun,images.kpack,podintent,app,services.serving
```
You will see output similar to the following example that shows the objects that were created by the Supply Chain Choreographer:
```console
NAME AGE
workload.carto.run/tanzu-java-web-app 109s
NAME URL READY STATUS AGE
gitrepository.source.toolkit.fluxcd.io/tanzu-java-web-app https://github.com/sample-accelerators/tanzu-java-web-app True Fetched revision: main/872ff44c8866b7805fb2425130edb69a9853bfdf 109s
NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
pipelinerun.tekton.dev/tanzu-java-web-app-4ftlb True Succeeded 104s 77s
NAME LATESTIMAGE READY
image.kpack.io/tanzu-java-web-app 10.188.0.3:5000/foo/tanzu-java-web-app@sha256:1d5bc4d3d1ffeb8629fbb721fcd1c4d28b896546e005f1efd98fbc4e79b7552c True
NAME READY REASON AGE
podintent.conventions.apps.tanzu.vmware.com/tanzu-java-web-app True 7s
NAME DESCRIPTION SINCE-DEPLOY AGE
app.kappctrl.k14s.io/tanzu-java-web-app Reconcile succeeded 1s 2s
NAME URL LATESTCREATED LATESTREADY READY REASON
service.serving.knative.dev/tanzu-java-web-app http://tanzu-java-web-app.developer.example.com tanzu-java-web-app-00001 tanzu-java-web-app-00001 Unknown IngressNotConfigured
```
### <a id="install-OOTB-test-scan"></a>Install OOTB Testing+Scanning
Follow these steps to install the OOTB Testing+Scanning supply chain:
> **Note:** When leveraging both Tanzu Build Service and Grype in your Tanzu Application Platform supply chain, you can receive enhanced scanning coverage for Java and Node.js workloads that includes application runtime layer dependencies.
>**Important:** The grype must be installed for scanning.
1. Supply Chain Security Tools - Scan is installed as part of the profiles.
Verify that both Scan Link and Grype Scanner are installed by running:
```console
tanzu package installed get scanning -n tap-install
tanzu package installed get grype -n tap-install
```
If the packages are not already installed, follow the steps in [Supply Chain Security Tools - Scan](install-components.md#install-scst-scan) to install the required scanning components.
During installation of the Grype Scanner, sample ScanTemplates are installed into the `default` namespace. If the workload is deployed into another namespace, these sample ScanTemplates also must be present in the other namespace. One way to accomplish this is to install Grype Scanner again, and provide the namespace in the values file.
A ScanPolicy is required and the following code must be in the required namespace. You can either add the namespace flag to the kubectl command or add the namespace field to the template itself. Run:
```console
kubectl apply -f - -o yaml << EOF
---
apiVersion: scanning.apps.tanzu.vmware.com/v1beta1
kind: ScanPolicy
metadata:
name: scan-policy
spec:
regoFile: |
package policies
default isCompliant = false
# Accepted Values: "Critical", "High", "Medium", "Low", "Negligible", "UnknownSeverity"
violatingSeverities := ["Critical","High","UnknownSeverity"]
ignoreCVEs := []
contains(array, elem) = true {
array[_] = elem
} else = false { true }
isSafe(match) {
fails := contains(violatingSeverities, match.Ratings.Rating[_].Severity)
not fails
}
isSafe(match) {
ignore := contains(ignoreCVEs, match.Id)
ignore
}
isCompliant = isSafe(input.currentVulnerability)
EOF
```
2. (optional) To persist and query the vulnerability results post-scan, ensure that [Supply Chain Security Tools - Store](scst-store/overview.md) is installed using the following command. The Tanzu Application Platform profiles install the package by default.
```console
tanzu package installed get metadata-store -n tap-install
```
If the package is not installed, follow [the installation instructions](install-components.md#install-scst-store).
3. Update the profile to use the supply chain with testing and scanning by
updating `tap-values.yaml` (the file used to customize the profile in `tanzu
package install tap --values-file=...`) with the following changes:
```console
- supply_chain: testing
+ supply_chain: testing_scanning
- ootb_supply_chain_testing:
+ ootb_supply_chain_testing_scanning:
registry:
server: "<SERVER-NAME>"
repository: "<REPO-NAME>"
```
4. Update the `tap` package:
```console
tanzu package installed update tap -p tap.tanzu.vmware.com -v VERSION-NUMBER --values-file tap-values.yaml -n tap-install
```
Where `VERSION-NUMBER` is your Tanzu Application Platform version. For example, `{{ vars.tap_version }}`.
#### <a id="test-scan-workload-update"></a>Workload update
To connect the new supply chain to the workload, update the workload to point to your Tekton
pipeline:
1. Update the workload by running the following using the Tanzu CLI:
```console
tanzu apps workload create tanzu-java-web-app \
--git-repo https://github.com/sample-accelerators/tanzu-java-web-app \
--git-branch main \
--type web \
--label apps.tanzu.vmware.com/has-tests=true \
--yes
```
Example output:
```console
Create workload:
1 + |---
2 + |apiVersion: carto.run/v1alpha1
3 + |kind: Workload
4 + |metadata:
5 + | labels:
6 + | apps.tanzu.vmware.com/has-tests: "true"
7 + | apps.tanzu.vmware.com/workload-type: web
8 + | name: tanzu-java-web-app
9 + | namespace: default
10 + |spec:
11 + | source:
12 + | git:
13 + | ref:
14 + | branch: main
15 + | url: https://github.com/sample-accelerators/tanzu-java-web-app
? Do you want to create this workload? Yes
Created workload "tanzu-java-web-app"
```
1. After accepting the workload creation, view the new resources that the workload created by running:
```console
kubectl get workload,gitrepository,sourcescan,pipelinerun,images.kpack,imagescan,podintent,app,services.serving
```
The following is an example output, which shows the objects that the Supply Chain Choreographer created:
```console
NAME AGE
workload.carto.run/tanzu-java-web-app 109s
NAME URL READY STATUS AGE
gitrepository.source.toolkit.fluxcd.io/tanzu-java-web-app https://github.com/sample-accelerators/tanzu-java-web-app True Fetched revision: main/872ff44c8866b7805fb2425130edb69a9853bfdf 109s
NAME PHASE SCANNEDREVISION SCANNEDREPOSITORY AGE CRITICAL HIGH MEDIUM LOW UNKNOWN CVETOTAL
sourcescan.scanning.apps.tanzu.vmware.com/tanzu-java-web-app Completed 187850b39b754e425621340787932759a0838795 https://github.com/sample-accelerators/tanzu-java-web-app 90s
NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
pipelinerun.tekton.dev/tanzu-java-web-app-4ftlb True Succeeded 104s 77s
NAME LATESTIMAGE READY
image.kpack.io/tanzu-java-web-app 10.188.0.3:5000/foo/tanzu-java-web-app@sha256:1d5bc4d3d1ffeb8629fbb721fcd1c4d28b896546e005f1efd98fbc4e79b7552c True
NAME PHASE SCANNEDIMAGE AGE CRITICAL HIGH MEDIUM LOW UNKNOWN CVETOTAL
imagescan.scanning.apps.tanzu.vmware.com/tanzu-java-web-app Completed 10.188.0.3:5000/foo/tanzu-java-web-app@sha256:1d5bc4d3d1ffeb8629fbb721fcd1c4d28b896546e005f1efd98fbc4e79b7552c 14s
NAME READY REASON AGE
podintent.conventions.apps.tanzu.vmware.com/tanzu-java-web-app True 7s
NAME DESCRIPTION SINCE-DEPLOY AGE
app.kappctrl.k14s.io/tanzu-java-web-app Reconcile succeeded 1s 2s
NAME URL LATESTCREATED LATESTREADY READY REASON
service.serving.knative.dev/tanzu-java-web-app http://tanzu-java-web-app.developer.example.com tanzu-java-web-app-00001 tanzu-java-web-app-00001 Unknown IngressNotConfigured
```
If the source or image scan has a "Failed" phase, then the scan has failed compliance and the supply chain stops.
#### <a id="query-for-vuln"></a> Query for vulnerabilities
Scan reports are automatically saved to the [Supply Chain Security Tools - Store](scst-store/overview.md), and can be queried for vulnerabilities and dependencies. For example, open-source software (OSS) or third party packages.
1. Query the tanzu-java-web-app image dependencies and vulnerabilities with the following commands:
```console
insight image get --digest DIGEST
insight image vulnerabilities --digest DIGEST
```
`DIGEST` is the component version, or image digest printed in the `KUBECTL GET` command.
> **Important:** The `Insight CLI` is separate from the Tanzu CLI.
See [Tanzu Insight plug-in overview](cli-plugins/insight/cli-overview.md)
additional information and examples.
<br>
### <a id="successful-deploy"></a>Congratulations! You have successfully deployed your application on the Tanzu Application Platform.
Through the next two sections to learn about recommended supply chain security best practices and access to a powerful Services Journey experience on the Tanzu Application Platform by enabling several advanced use cases.
## <a id="config-img-sign-verify"></a>Section 4: Configure image signing and verification in your supply chain
In this section, you are about to:
- Configure your supply chain to sign your image builds.
- Configure an admission control policy to verify image signatures before admitting Pods to the cluster.
### <a id="config-sc-to-img-builds"></a>Configure your supply chain to sign your image builds
1. Configure Tanzu Build Service to sign your container image builds by using cosign. See [Managing Image Resources and Builds](https://docs.vmware.com/en/Tanzu-Build-Service/1.6/vmware-tanzu-build-service/GUID-managing-images.html) for instructions.
2. Create a `values.yaml` file, and install the sign supply chain security tools and image policy web-hook. See [Install Supply Chain Security Tools - Sign](install-components.html#install-scst-sign) for instructions.
3. Configure a `ClusterImagePolicy` resource to verify image signatures when deploying resources. The resource must be named `image-policy`.
For example:
```yaml
---
apiVersion: signing.apps.tanzu.vmware.com/v1beta1
kind: ClusterImagePolicy
metadata:
name: image-policy
spec:
verification:
exclude:
resources
namespaces:
- kube-system
- test-namespace
- <TAP system namespaces>
keys:
- name: first-key
publicKey: |
-----BEGIN PUBLIC KEY-----
<content ...>
-----END PUBLIC KEY-----
images:
- namePattern: registry.example.org/myproject/*
keys:
- name: first-key
```
> **Note:** System namespaces specific to your cloud provider might need to be excluded from the policy.
To prevent the Image Policy Webhook from blocking components of Tanzu Application Platform, VMware recommends configuring exclusions for Tanzu Application Platform system namespaces listed in [Create a `ClusterImagePolicy` resource](scst-sign/configuring.md#create-cip-resource).
When you apply the `ClusterImagePolicy` resource, your cluster requires valid signatures for all images that match the `namePattern:` you define in the configuration. For more information about configuring an image signature policy, see [Configuring Supply Chain Security Tools - Sign](scst-sign/configuring.html).
#### <a id="config-img-next-steps"></a>Next steps
- [Overview for Supply Chain Security Tools - Sign](scst-sign/overview.md)
- [Configuring Supply Chain Security Tools - Sign](scst-sign/configuring.md)
- [Supply Chain Security Tools - Sign known issues](release-notes.md)
### <a id="intro-vuln-scan-and-more"></a>Scan and Store: Introducing vulnerability scanning and metadata storage to your Supply Chain
**Overview**
This feature set allows an application operator to introduce source code and image vulnerability scanning, and scan-time rules, to their Tanzu Application Platform Supply Chain. The scan-time rules prevent critical vulnerabilities from flowing to the supply chain unresolved.
[Supply Chain Security Tools - Store](scst-store/overview.md) takes the vulnerability scanning results and stores them. Users can query for information about CVEs, images, packages, and their relationships by using the using the `tanzu insight` CLI plug-in, or directly from the API.
**Features**
- Scan source code repositories and images for known CVEs before deploying to a cluster
- Identify CVEs by scanning continuously on each new code commit or each new image built
- Analyze scan results against user-defined policies using Open Policy Agent
- Produce vulnerability scan results and post them to the Supply Chain Security Tools - Store where they can be queried
- Query the store for such use cases as:
- What images and packages are affected by a specific vulnerability?
- What source code repos are affected by a specific vulnerability?
- What packages and vulnerabilities does a particular image have?
To try the scan and store features as individual one-off scans, see [Scan samples](scst-scan/samples/overview.md).
To try the scan and store features in a supply chain, see [Section 3: Add testing and security scanning to your application](#add-test-and-scan).
#### <a id="scst-scan-next-steps"></a>Next steps
- [Configure Code Repositories and Image Artifacts to be Scanned](scst-scan/scan-crs.md)
- [Code and Image Compliance Policy Enforcement Using Open Policy Agent (OPA)](scst-scan/policies.md)
- [How to Create a ScanTemplate](scst-scan/create-scan-template.md)
- [Viewing and Understanding Scan Status Conditions](scst-scan/results.md)
- [Observing and Troubleshooting](scst-scan/observing.md)
- [Tanzu Insight plug-in overview](../cli-plugins/insight/cli-overview.md)
## <a id='stk'></a> Section 5: Consuming services on Tanzu Application Platform
In this section you will learn about working with backing services such as
RabbitMQ, PostgreSQL and MySQL as part of Tanzu Application Platform.
Particular focus will be given to binding application workloads to service instances,
which is the most common use case for services.