Skip to content

Commit 86a9c5a

Browse files
nithyatsunithyatsu
committed
first draft
1 parent 4c86cd2 commit 86a9c5a

File tree

3 files changed

+199
-0
lines changed

3 files changed

+199
-0
lines changed

‎docs/content/reference/resource-schema/udt/_index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
type: docs
3+
title: "User defined types"
4+
linkTitle: "User defined types"
5+
description: "Learn about the schema of user defined type resources which can be used in your applications"
6+
weight: 500
7+
---

‎docs/content/reference/resource-schema/udt/index.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
type: docs
3+
title: "Overview: User Defined Type Resource schemas"
4+
linkTitle: "Overview"
5+
description: "Schema docs for the resources of user defined type that can comprise a Radius Application"
6+
categories: "Overview"
7+
weight: 100
8+
---
9+
10+
## User defined types
11+
12+
Radius supports creation of user defined types, which have an user defined schema.
13+
These types can be managed using [rad resource-type](docs/content/reference/cli/rad_resource-type.md) command.
14+
15+
`rad resource-type create` command takes a resource type manifest as input argument. Users define an openAPI schema for their type
16+
in this manifest. A sample manifest is shown below:
17+
18+
{{< codetab >}}
19+
20+
{{< rad file="snippets/postgres.yaml" embed=true marker="//SAMPLE" >}}
21+
22+
{{< /codetab >}}
23+
24+
## Resource type manifest schema
25+
26+
Manifest file has below keys at the top level:
27+
28+
| Key | Description | Example |
29+
|-----|-------------|---------|
30+
| **name** | The namespace in which the resource type is registered | `MyCompany.Resources` |
31+
| [**types**](#types) | type-names in the specified namespace. The resource type manifest usually has one type that should be registered. | `postgresDatabases` |
32+
33+
### types
34+
35+
| Key | Description | Example |
36+
|-----|-------------|---------|
37+
| [**name of the resource type**](#resource-type-name) | The namespace in which the resource type is registered | `MyCompany.Resources` |
38+
39+
## resource type name
40+
41+
| Key | Description | Example |
42+
|-----|-------------|---------|
43+
| **description** | Description of the resource type | `A postgreSQL database` |
44+
| [**apiVersions**](#apiVersions) | api-versions which support this resource type | `2025-01-01-preview` |
45+
46+
## apiVersions
47+
48+
| Key | Description | Example |
49+
|-----|-------------|---------|
50+
| [**apiversion name**](#api-version-name) | a specific api version which supports this resource type | `2025-01-01-preview` |
51+
52+
## api version name
53+
54+
| Key | Description |
55+
|-----|-------------|
56+
| [**schema**](#schema) | openAPI v3 structural schema of the resource type in a specific api version. Radius supports a subset of open API capabilities. This is covered in subsequent sections |
57+
58+
## schema
59+
60+
`schema` holds the description of the structural schema for new resource type use using [Open API v3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#schema-object)
61+
62+
| Key | Description |
63+
|-----|-------------|
64+
| **type**| type of `schema`. This is always object, representing a open API v3 object |
65+
| [**properties**](#properties)| properties which are valid for a resource of the specified resource type|
66+
| **required** | list of properties that are required for a resource |
67+
68+
### properties
69+
70+
| Key | Description | Example |
71+
|-----|-------------|---------|
72+
| **type**| type of `schema`. This is always object, representing a open API v3 object | |
73+
| [**property name**](#property-name)| A property name. Property names MUST be strings and SHOULD conform to the regular expression: ^[a-zA-Z0-9\.\-_]+$.| logging-verbosity |
74+
75+
### property name
76+
77+
| Key | Description | Example |
78+
|-----|-------------|---------|
79+
| **type**| type of the value of property. This can be any primitive type defined in [Open API v3 data types](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#data-types) OR an array OR a map | [examples](#examples) |
80+
81+
82+
#### Examples
83+
84+
##### primitive type property
85+
86+
```
87+
properties:
88+
size:
89+
type: string
90+
description: The size of database to provision
91+
enum:
92+
- S
93+
- M
94+
- L
95+
- XL
96+
host:
97+
type: string
98+
description: hostname
99+
maxLength: 20
100+
```
101+
102+
##### array
103+
104+
`array` must specify a `type` for item
105+
106+
```
107+
schema:
108+
openAPIV3Schema:
109+
type: object
110+
properties:
111+
ports:
112+
type: array
113+
description: "ports this resource binds to"
114+
item:
115+
type: integer
116+
format: uint32
117+
```
118+
119+
##### map
120+
121+
We support map through `addionalProperties`. This is useful when the resource type allows for dynamic (user defined) keys. We still must specify a type for the value of the property.
122+
123+
```
124+
schema:
125+
openAPIV3Schema:
126+
type: object
127+
properties:
128+
name:
129+
type: string
130+
description: The name of the resource
131+
labels:
132+
type: object
133+
description: A map of labels for the resource
134+
additionalProperties:
135+
type: string
136+
```
137+
138+
139+
140+

‎docs/content/reference/resource-schema/udt/snippets/postgres.yaml

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: MyCompany.Resources
2+
types:
3+
postgresDatabases:
4+
description: A postgreSQL database
5+
apiVersions:
6+
'2025-01-01-preview':
7+
schema:
8+
type: object
9+
properties:
10+
size:
11+
type: string
12+
description: |
13+
The size of database to provision:
14+
- 'S': 0.5 vCPU, 2 GiB memory, 20 GiB storage
15+
- 'M': 1 vCPU, 4 GiB memory, 40 GiB storage
16+
- 'L': 2 vCPU, 8 GiB memory, 60 GiB storage
17+
- 'XL': 4 vCPU, 16 GiB memory, 100 GiB storage
18+
enum:
19+
- S
20+
- M
21+
- L
22+
- XL
23+
logging-verbosity:
24+
type: string
25+
description: >
26+
The logging level for the database:
27+
- 'TERSE': Not recommended; does not provide guidance on what to do about an error
28+
- 'DEFAULT': Recommended level
29+
- 'VERBOSE': Use only if you plan to actually look up the Postgres source code
30+
enum:
31+
- TERSE
32+
- DEFAULT
33+
- VERBOSE
34+
connection-string:
35+
type: string
36+
readOnly: true
37+
description: 'Fully qualified string to connect to the resource'
38+
env-variable: POSTGRESQL_CONNECTION_STRING
39+
credentials:
40+
type: object
41+
readOnly: true
42+
properties:
43+
username:
44+
type: string
45+
description: 'Username for the database'
46+
env-variable: POSTGRESQL_USERNAME
47+
password:
48+
type: string
49+
description: 'Password for the database user'
50+
env-variable: POSTGRESQL_PASSWORD
51+
required:
52+
- size

0 commit comments

Comments
 (0)