Skip to content

Commit 32e5b5c

Browse files
lbroudouxlbroudoux
committed
feat: #52 #47 Add advanced documentation on APISource
Signed-off-by: Laurent Broudoux <[email protected]>
1 parent d993975 commit 32e5b5c

File tree

2 files changed

+91
-14
lines changed

2 files changed

+91
-14
lines changed

‎documentation/apisource-cr.md

Lines changed: 90 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11

22
## Overview
33

4+
The `APISource` Custom Resource (CR) allows you to define mocks and importers in Microcks. This resources allows
5+
you to define the artifacts to be imported or some importers to be used to import them and keep them synchronized.
6+
`APISource` Custom Resource Definition is currently defined using the `microcks.io/v1alpha1` API version. To access
7+
the full schema definition you may want to check the
8+
[apisources.microcks.io-v1.yml](../deploy/crd/apisources.microcks.io-v1.yml) file.
9+
410
The `APISource` is a [Microcks-dependent resource](./microcks-dependent-cr.md) as it needs to have a Microcks
511
instance to be managed by the operator first.
612

@@ -25,27 +31,97 @@ spec:
2531
* `spec.artifacts` contains one or more artifact specification details.
2632
* `spec.importers` contains one or more importer specification details.
2733

34+
Once created in your namespace, you can easily list the existing secret sources using:
35+
36+
```yaml
37+
$ kubectl get apisources -n m2
38+
NAME AGE
39+
tests-artifacts 1d
40+
```
41+
42+
and get access to a specific instance details using `kubectl get apisources/tests-artifacts -n m2 -o yaml`.
43+
The operator tracks the status of the reconciliation using the following structure in the `status` field
44+
of the resource:
45+
46+
```yaml
47+
kind: APISource
48+
metadata:
49+
annotations:
50+
microcks.io/instance: microcks
51+
spec:
52+
[...]
53+
status:
54+
conditions:
55+
- lastTransitionTime: "2024-10-31T22:11:14Z"
56+
message: API Pastry - 2.0:2.0.0
57+
status: READY
58+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/APIPastry-openapi.yaml
59+
- lastTransitionTime: "2024-10-31T22:11:15Z"
60+
message: io.github.microcks.grpc.hello.v1.HelloService:v1
61+
status: READY
62+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/hello-v1.proto
63+
- lastTransitionTime: "2024-10-31T22:11:15Z"
64+
message: io.github.microcks.grpc.hello.v1.HelloService:v1
65+
status: READY
66+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloService.metadata.yml
67+
- lastTransitionTime: "2024-10-31T22:11:16Z"
68+
message: io.github.microcks.grpc.hello.v1.HelloService:v1
69+
status: READY
70+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloService.postman.json
71+
- lastTransitionTime: "2024-10-31T22:11:16Z"
72+
message: Movie Graph API:1.0
73+
status: READY
74+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/films.graphql
75+
- lastTransitionTime: "2024-10-31T22:11:16Z"
76+
message: Movie Graph API:1.0
77+
status: READY
78+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/films-metadata.yml
79+
- lastTransitionTime: "2024-10-31T22:11:16Z"
80+
message: Movie Graph API:1.0
81+
status: READY
82+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/films-postman.json
83+
- lastTransitionTime: "2024-10-31T22:11:17Z"
84+
message: 67240085de8ad417f5cb4318
85+
status: READY
86+
type: https://raw.githubusercontent.com/microcks/microcks/master/samples/HelloService-soapui-project.xml
87+
observedGeneration: 0
88+
status: READY
89+
```
90+
91+
Basically, one `condition` is created per `artifact` and `importer` specification to track the reconciliation result and
92+
the global status is made available via the `status.status` field. The `type` field of the condition represents the
93+
artifact url in Microcks instance and the `message` field represents the API or importer unique identifier.
94+
95+
`importers` and Mock API discovered from `aritfacts` imported in Microcks are -by default- deleted when the custom resource
96+
is deleted. This behavior can be changed by setting the `keepAPIOnDelete` property to `true` in the `spec` section.
97+
2898
## Artifact specification details
2999

30-
| Property | Description |
31-
|----------------|----------------------------------|
32-
| `url` | **Mandatory**. |
33-
| `mainArtifact` | **Optional**. Default is `true`. |
34-
| `secretRef` | **Optional**. |
100+
Direct artifact declaration specification:
101+
102+
| Property | Description |
103+
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
104+
| `url` | **Mandatory**. The URL of artifact to import into Microcks instance. |
105+
| `mainArtifact` | **Optional**. Whether this artifact should be considered as a main/primary one oar as a secondary one. See [Multi-artifacts](https://microcks.io/documentation/explanations/multi-artifacts/) explanations. Default is `true`. |
106+
| `secretRef` | **Optional**. An optional Secret that can be used to fetch the artifact URL. See [`SecretSource`](./secretsource-cr.md) custom resource and [Microcks Secrets](https://microcks.io/documentation/guides/administration/secrets/) explanations. |
35107

36108
## Importer specification details
37109

38-
| Property | Description |
39-
|-----------------------------------|-----------------------------------|
40-
| `mainArtifact` | **Optional**. Default is `true`. |
41-
| `active` | **Optional**. Default is `true`. |
42-
| `repository.url` | **Mandatory**. |
43-
| `repository.disableSSLValidation` | **Optional**. Default is `false`. |
44-
| `repository.secretRef` | **Optional**. |
45-
| `labels` | **Optional**. |
110+
Importer declaration specification:
111+
112+
| Property | Description |
113+
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
114+
| `mainArtifact` | **Optional**. Whether this artifact should be considered as a main/primary one oar as a secondary one. See [Multi-artifacts](https://microcks.io/documentation/explanations/multi-artifacts/) explanations. Default is `true`. |
115+
| `active` | **Optional**. Whether this importer should be immediately activated. Default is `true`. |
116+
| `repository.url` | **Mandatory**. The URL of artifact to import into Microcks instance. |
117+
| `repository.disableSSLValidation` | **Optional**. Default is `false`. |
118+
| `repository.secretRef` | **Optional**. An optional Secret that can be used to fetch the artifact URL. See [`SecretSource`](./secretsource-cr.md) custom resource and [Microcks Secrets](https://microcks.io/documentation/guides/administration/secrets/) explanations. |
119+
| `labels` | **Optional**. A map of labels to set on created importer. |
46120

47121
## Example
48122

123+
Here is a full example below:
124+
49125
```yaml
50126
apiVersion: microcks.io/v1alpha1
51127
kind: APISource
@@ -54,6 +130,7 @@ metadata:
54130
annotations:
55131
microcks.io/instance: microcks
56132
spec:
133+
keepAPIOnDelete: false
57134
artifacts:
58135
- url: https://raw.githubusercontent.com/microcks/microcks/master/samples/APIPastry-openapi.yaml
59136
mainArtifact: true

‎documentation/secretsource-cr.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
## Overview
33

44
The `SecretSource` Custom Resource (CR) allows you to define secrets in Microcks. Those secrets can be directly specified
5-
in the resource of synchronized from Kubernetes `Secrets` existing in the same namespace.
5+
in the resource or synchronized from Kubernetes `Secrets` existing in the same namespace.
66
`SecretSource` Custom Resource Definition is currently defined using the `microcks.io/v1alpha1` API version. To access
77
the full schema definition you may want to check the
88
[secretsources.microcks.io-v1.yml](../deploy/crd/secretsources.microcks.io-v1.yml) file.

0 commit comments

Comments
 (0)