Skip to content

Commit 4f26435

Browse files
mimihalescumimihalescu
authored
Merge pull request #1 from ionos-cloud/docs/gitbook-integration
feat: add files for Gitbook integration
2 parents 626df7a + bd4f520 commit 4f26435

File tree

3 files changed

+302
-0
lines changed

3 files changed

+302
-0
lines changed

‎.gitbook.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
root: docs
2+
structure:
3+
readme: README.md
4+
summary: summary.md

‎docs/CHANGELOG.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## SDK Go Data Platform v1.0.0
2+
3+
### Overview
4+
This is the first release of the SDK Go Data Platform.
5+
Managed Stackable Data Platform by IONOS Cloud provides a preconfigured Kubernetes cluster with pre-installed and managed Stackable operators. After the provision of these Stackable operators, the customer can interact with them directly and build his desired application on top of the Stackable Platform.
6+
7+
8+
**Note:** Data Platform is currently in the **Early Access (EA)** phase. We recommend keeping usage and testing to non-production critical applications. Please contact your sales representative or support for more information.

‎docs/README.md

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
# Go API client for ionoscloud
2+
3+
Managed Stackable Data Platform by IONOS Cloud provides a preconfigured Kubernetes cluster
4+
with pre-installed and managed Stackable operators. After the provision of these Stackable operators,
5+
the customer can interact with them directly
6+
and build his desired application on top of the Stackable Platform.
7+
8+
Managed Stackable Data Platform by IONOS Cloud can be configured through the IONOS Cloud API
9+
in addition or as an alternative to the \"Data Center Designer\" (DCD).
10+
11+
## Getting Started
12+
13+
To get your DataPlatformCluster up and running, the following steps needs to be performed.
14+
15+
### IONOS Cloud Account
16+
17+
The first step is the creation of a IONOS Cloud account if not already existing.
18+
19+
To register a **new account** visit [cloud.ionos.com](https://cloud.ionos.com/compute/signup).
20+
21+
### Virtual Datacenter (VDC)
22+
23+
The Managed Data Stack needs a virtual datacenter (VDC) hosting the cluster.
24+
This could either be a VDC that already exists, especially if you want to connect the managed DataPlatform
25+
to other services already running within your VDC. Otherwise, if you want to place the Managed Data Stack in
26+
a new VDC or you have not yet created a VDC, you need to do so.
27+
28+
A new VDC can be created via the IONOS Cloud API, the IONOS-CLI or the DCD Web interface.
29+
For more information, see the [official documentation](https://docs.ionos.com/cloud/getting-started/tutorials/data-center-basics)
30+
31+
### Get a authentication token
32+
33+
To interact with this API a user specific authentication token is needed.
34+
This token can be generated using the IONOS-CLI the following way:
35+
36+
```
37+
ionosctl token generate
38+
```
39+
40+
For more information [see](https://docs.ionos.com/cli-ionosctl/subcommands/authentication/token-generate)
41+
42+
### Create a new DataPlatformCluster
43+
44+
Before using Managed Stackable Data Platform, a new DataPlatformCluster must be created.
45+
46+
To create a cluster, use the [Create DataPlatformCluster](paths./clusters.post) API endpoint.
47+
48+
The provisioning of the cluster might take some time. To check the current provisioning status,
49+
you can query the cluster by calling the [Get Endpoint](#/DataPlatformCluster/getCluster) with the cluster ID
50+
that was presented to you in the response of the create cluster call.
51+
52+
### Add a DataPlatformNodePool
53+
54+
To deploy and run a Stackable service, the cluster must have enough computational resources. The node pool
55+
that is provisioned along with the cluster is reserved for the Stackable operators.
56+
You may create further node pools with resources tailored to your use-case.
57+
58+
To create a new node pool use the [Create DataPlatformNodepool](paths./clusters/{clusterId}/nodepools.post)
59+
endpoint.
60+
61+
### Receive Kubeconfig
62+
63+
Once the DataPlatformCluster is created, the kubeconfig can be accessed by the API.
64+
The kubeconfig allows the interaction with the provided cluster as with any regular Kubernetes cluster.
65+
66+
The kubeconfig can be downloaded with the [Get Kubeconfig](paths./clusters/{clusterId}/kubeconfig.get) endpoint
67+
using the cluster ID of the created DataPlatformCluster.
68+
69+
### Create Stackable Service
70+
71+
To create the desired application, the Stackable service needs to be provided,
72+
using the received kubeconfig and
73+
[deploy a Stackable service](https://docs.stackable.tech/home/getting_started.html#_deploying_stackable_services)
74+
75+
## Authorization
76+
77+
All endpoints are secured, so only an authenticated user can access them.
78+
As Authentication mechanism the default IONOS Cloud authentication mechanism
79+
is used. A detailed description can be found [here](https://api.ionos.com/docs/authentication/).
80+
81+
### Basic-Auth
82+
83+
The basic auth scheme uses the IONOS Cloud user credentials in form of a Basic Authentication Header
84+
accordingly to [RFC7617](https://datatracker.ietf.org/doc/html/rfc7617)
85+
86+
### API-Key as Bearer Token
87+
88+
The Bearer auth token used at the API-Gateway is a user related token created with the IONOS-CLI.
89+
(See the [documentation](https://docs.ionos.com/cli-ionosctl/subcommands/authentication/token-generate) for details)
90+
For every request to be authenticated, the token is passed as 'Authorization Bearer' header along with the request.
91+
92+
### Permissions and access roles
93+
94+
Currently, an admin can see and manipulate all resources in a contract.
95+
A normal authenticated user can only see and manipulate resources he created.
96+
97+
98+
## Components
99+
100+
The Managed Stackable Data Platform by IONOS Cloud consists of two components.
101+
The concept of a DataPlatformClusters and the backing DataPlatformNodePools the cluster is build on.
102+
103+
### DataPlatformCluster
104+
105+
A DataPlatformCluster is the virtual instance of the customer services and operations running the managed Services like Stackable operators.
106+
A DataPlatformCluster is a Kubernetes Cluster in the VDC of the customer.
107+
Therefore, it's possible to integrate the cluster with other resources as vLANs e.G.
108+
to shape the datacenter in the customer's need and integrate the cluster within the topology the customer wants to build.
109+
110+
In addition to the Kubernetes cluster a small node pool is provided which is exclusively used to run the Stackable operators.
111+
112+
### DataPlatformNodePool
113+
114+
A DataPlatformNodePool represents the physical machines a DataPlatformCluster is build on top.
115+
All nodes within a node pool are identical in setup.
116+
The nodes of a pool are provisioned into virtual data centers at a location of your choice
117+
and you can freely specify the properties of all the nodes at once before creation.
118+
119+
Nodes in node pools provisioned by the Managed Stackable Data Platform Cloud API are readonly in the customer's VDC
120+
and can only be modified or deleted via the API.
121+
122+
### References
123+
124+
125+
## Overview
126+
This API client was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the [OpenAPI-spec](https://www.openapis.org/) from a remote server, you can easily generate an API client.
127+
128+
- API version: 0.0.7
129+
- Package version: 1.0.0
130+
- Build package: org.openapitools.codegen.languages.GoClientCodegen
131+
For more information, please visit [https://ionos.com](https://ionos.com)
132+
133+
## Installation
134+
135+
Install the following dependencies:
136+
137+
```shell
138+
go get github.com/stretchr/testify/assert
139+
go get golang.org/x/oauth2
140+
go get golang.org/x/net/context
141+
```
142+
143+
Put the package under your project folder and add the following in import:
144+
145+
```golang
146+
import sw "./ionoscloud"
147+
```
148+
149+
To use a proxy, set the environment variable `HTTP_PROXY`:
150+
151+
```golang
152+
os.Setenv("HTTP_PROXY", "http://proxy_name:proxy_port")
153+
```
154+
155+
## Configuration of Server URL
156+
157+
Default configuration comes with `Servers` field that contains server objects as defined in the OpenAPI specification.
158+
159+
### Select Server Configuration
160+
161+
For using other server than the one defined on index 0 set context value `sw.ContextServerIndex` of type `int`.
162+
163+
```golang
164+
ctx := context.WithValue(context.Background(), sw.ContextServerIndex, 1)
165+
```
166+
167+
### Templated Server URL
168+
169+
Templated server URL is formatted using default variables from configuration or from context value `sw.ContextServerVariables` of type `map[string]string`.
170+
171+
```golang
172+
ctx := context.WithValue(context.Background(), sw.ContextServerVariables, map[string]string{
173+
"basePath": "v2",
174+
})
175+
```
176+
177+
Note, enum values are always validated and all unused variables are silently ignored.
178+
179+
### URLs Configuration per Operation
180+
181+
Each operation can use different server URL defined using `OperationServers` map in the `Configuration`.
182+
An operation is uniquely identifield by `"{classname}Service.{nickname}"` string.
183+
Similar rules for overriding default operation server index and variables applies by using `sw.ContextOperationServerIndices` and `sw.ContextOperationServerVariables` context maps.
184+
185+
```
186+
ctx := context.WithValue(context.Background(), sw.ContextOperationServerIndices, map[string]int{
187+
"{classname}Service.{nickname}": 2,
188+
})
189+
ctx = context.WithValue(context.Background(), sw.ContextOperationServerVariables, map[string]map[string]string{
190+
"{classname}Service.{nickname}": {
191+
"port": "8443",
192+
},
193+
})
194+
```
195+
196+
## Documentation for API Endpoints
197+
198+
All URIs are relative to *https://api.ionos.com/dataplatform*
199+
200+
Class | Method | HTTP request | Description
201+
------------ | ------------- | ------------- | -------------
202+
*DataPlatformClusterApi* | [**CreateCluster**](docs/api/DataPlatformClusterApi.md#createcluster) | **Post** /clusters | Create a DataPlatformCluster
203+
*DataPlatformClusterApi* | [**DeleteCluster**](docs/api/DataPlatformClusterApi.md#deletecluster) | **Delete** /clusters/{clusterId} | Delete DataPlatformCluster
204+
*DataPlatformClusterApi* | [**GetCluster**](docs/api/DataPlatformClusterApi.md#getcluster) | **Get** /clusters/{clusterId} | Retrieve a DataPlatformCluster
205+
*DataPlatformClusterApi* | [**GetClusterKubeconfig**](docs/api/DataPlatformClusterApi.md#getclusterkubeconfig) | **Get** /clusters/{clusterId}/kubeconfig | Read the kubeconfig
206+
*DataPlatformClusterApi* | [**GetClusters**](docs/api/DataPlatformClusterApi.md#getclusters) | **Get** /clusters | List DataPlatformCluster
207+
*DataPlatformClusterApi* | [**PatchCluster**](docs/api/DataPlatformClusterApi.md#patchcluster) | **Patch** /clusters/{clusterId} | Partially modify a DataPlatformCluster
208+
*DataPlatformMetaDataApi* | [**VersionsGet**](docs/api/DataPlatformMetaDataApi.md#versionsget) | **Get** /versions | Managed Data Stack API version
209+
*DataPlatformNodePoolApi* | [**CreateClusterNodepool**](docs/api/DataPlatformNodePoolApi.md#createclusternodepool) | **Post** /clusters/{clusterId}/nodepools | Create a DataPlatformNodePool for a distinct DataPlatformCluster
210+
*DataPlatformNodePoolApi* | [**DeleteClusterNodepool**](docs/api/DataPlatformNodePoolApi.md#deleteclusternodepool) | **Delete** /clusters/{clusterId}/nodepools/{nodepoolId} | Remove node pool from DataPlatformCluster.
211+
*DataPlatformNodePoolApi* | [**GetClusterNodepool**](docs/api/DataPlatformNodePoolApi.md#getclusternodepool) | **Get** /clusters/{clusterId}/nodepools/{nodepoolId} | Retrieve a DataPlatformNodePool
212+
*DataPlatformNodePoolApi* | [**GetClusterNodepools**](docs/api/DataPlatformNodePoolApi.md#getclusternodepools) | **Get** /clusters/{clusterId}/nodepools | List the DataPlatformNodePools of a DataPlatformCluster
213+
*DataPlatformNodePoolApi* | [**PatchClusterNodepool**](docs/api/DataPlatformNodePoolApi.md#patchclusternodepool) | **Patch** /clusters/{clusterId}/nodepools/{nodepoolId} | Partially modify a DataPlatformNodePool
214+
215+
216+
## Documentation For Models
217+
218+
- [AvailabilityZone](docs/models/AvailabilityZone.md)
219+
- [Cluster](docs/models/Cluster.md)
220+
- [ClusterListResponseData](docs/models/ClusterListResponseData.md)
221+
- [ClusterResponseData](docs/models/ClusterResponseData.md)
222+
- [CreateClusterProperties](docs/models/CreateClusterProperties.md)
223+
- [CreateClusterRequest](docs/models/CreateClusterRequest.md)
224+
- [CreateNodePoolProperties](docs/models/CreateNodePoolProperties.md)
225+
- [CreateNodePoolRequest](docs/models/CreateNodePoolRequest.md)
226+
- [ErrorMessage](docs/models/ErrorMessage.md)
227+
- [ErrorResponse](docs/models/ErrorResponse.md)
228+
- [MaintenanceWindow](docs/models/MaintenanceWindow.md)
229+
- [Metadata](docs/models/Metadata.md)
230+
- [NodePool](docs/models/NodePool.md)
231+
- [NodePoolListResponseData](docs/models/NodePoolListResponseData.md)
232+
- [NodePoolResponseData](docs/models/NodePoolResponseData.md)
233+
- [PatchClusterProperties](docs/models/PatchClusterProperties.md)
234+
- [PatchClusterRequest](docs/models/PatchClusterRequest.md)
235+
- [PatchNodePoolProperties](docs/models/PatchNodePoolProperties.md)
236+
- [PatchNodePoolRequest](docs/models/PatchNodePoolRequest.md)
237+
- [StorageType](docs/models/StorageType.md)
238+
239+
240+
## Documentation For Authorization
241+
242+
243+
244+
### basicAuth
245+
246+
- **Type**: HTTP basic authentication
247+
248+
Example
249+
250+
```golang
251+
auth := context.WithValue(context.Background(), sw.ContextBasicAuth, sw.BasicAuth{
252+
UserName: "username",
253+
Password: "password",
254+
})
255+
r, err := client.Service.Operation(auth, args)
256+
```
257+
258+
259+
### tokenAuth
260+
261+
- **Type**: HTTP Bearer token authentication
262+
263+
Example
264+
265+
```golang
266+
auth := context.WithValue(context.Background(), sw.ContextAccessToken, "BEARERTOKENSTRING")
267+
r, err := client.Service.Operation(auth, args)
268+
```
269+
270+
271+
## Documentation for Utility Methods
272+
273+
Due to the fact that model structure members are all pointers, this package contains
274+
a number of utility functions to easily obtain pointers to values of basic types.
275+
Each of these functions takes a value of the given basic type and returns a pointer to it:
276+
277+
* `PtrBool`
278+
* `PtrInt`
279+
* `PtrInt32`
280+
* `PtrInt64`
281+
* `PtrFloat`
282+
* `PtrFloat32`
283+
* `PtrFloat64`
284+
* `PtrString`
285+
* `PtrTime`
286+
287+
## Author
288+
289+
290+

0 commit comments

Comments
 (0)