atlascloudsdk 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- atlascloudsdk-0.1.1/ATLAS_SDK_GUIDE.md +13 -0
- atlascloudsdk-0.1.1/CHANGELOG.md +16 -0
- atlascloudsdk-0.1.1/LICENSE +21 -0
- atlascloudsdk-0.1.1/MANIFEST.in +7 -0
- atlascloudsdk-0.1.1/PKG-INFO +222 -0
- atlascloudsdk-0.1.1/README.md +190 -0
- atlascloudsdk-0.1.1/docs/examples.md +202 -0
- atlascloudsdk-0.1.1/docs/index.md +50 -0
- atlascloudsdk-0.1.1/docs/production-readiness.md +25 -0
- atlascloudsdk-0.1.1/docs/sdk-flow.md +587 -0
- atlascloudsdk-0.1.1/examples/__init__.py +1 -0
- atlascloudsdk-0.1.1/examples/auth.py +26 -0
- atlascloudsdk-0.1.1/examples/compute_units.py +53 -0
- atlascloudsdk-0.1.1/examples/instances.py +98 -0
- atlascloudsdk-0.1.1/examples/networks.py +66 -0
- atlascloudsdk-0.1.1/examples/projects.py +59 -0
- atlascloudsdk-0.1.1/examples/security_groups.py +108 -0
- atlascloudsdk-0.1.1/examples/ssh_keys.py +61 -0
- atlascloudsdk-0.1.1/examples/vdc.py +53 -0
- atlascloudsdk-0.1.1/mkdocs.yml +11 -0
- atlascloudsdk-0.1.1/pyproject.toml +68 -0
- atlascloudsdk-0.1.1/setup.cfg +4 -0
- atlascloudsdk-0.1.1/src/atlas/__init__.py +57 -0
- atlascloudsdk-0.1.1/src/atlas/_http/__init__.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/_http/transport.py +352 -0
- atlascloudsdk-0.1.1/src/atlas/auth.py +245 -0
- atlascloudsdk-0.1.1/src/atlas/cli/__init__.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/__init__.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/auth.py +62 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/gpu.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/instances.py +188 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/kubernetes.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/network.py +41 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/projects.py +53 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/security_groups.py +177 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/ssh.py +88 -0
- atlascloudsdk-0.1.1/src/atlas/cli/commands/vdc.py +37 -0
- atlascloudsdk-0.1.1/src/atlas/cli/context.py +23 -0
- atlascloudsdk-0.1.1/src/atlas/cli/main.py +26 -0
- atlascloudsdk-0.1.1/src/atlas/cli/output.py +6 -0
- atlascloudsdk-0.1.1/src/atlas/cli/token_store.py +72 -0
- atlascloudsdk-0.1.1/src/atlas/client.py +216 -0
- atlascloudsdk-0.1.1/src/atlas/config.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/connection.py +85 -0
- atlascloudsdk-0.1.1/src/atlas/exceptions.py +139 -0
- atlascloudsdk-0.1.1/src/atlas/models/__init__.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/models/gpu.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/models/kubernetes.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/models/project.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/pagination.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/resources/__init__.py +5 -0
- atlascloudsdk-0.1.1/src/atlas/resources/base.py +25 -0
- atlascloudsdk-0.1.1/src/atlas/resources/compute.py +35 -0
- atlascloudsdk-0.1.1/src/atlas/resources/compute_units.py +27 -0
- atlascloudsdk-0.1.1/src/atlas/resources/gpu.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/resources/instances.py +82 -0
- atlascloudsdk-0.1.1/src/atlas/resources/kubernetes.py +1 -0
- atlascloudsdk-0.1.1/src/atlas/resources/networks.py +69 -0
- atlascloudsdk-0.1.1/src/atlas/resources/projects.py +42 -0
- atlascloudsdk-0.1.1/src/atlas/resources/security_groups.py +115 -0
- atlascloudsdk-0.1.1/src/atlas/resources/ssh_keys.py +44 -0
- atlascloudsdk-0.1.1/src/atlas/resources/vdc.py +39 -0
- atlascloudsdk-0.1.1/src/atlas/version.py +3 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/PKG-INFO +222 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/SOURCES.txt +67 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/dependency_links.txt +1 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/entry_points.txt +2 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/requires.txt +11 -0
- atlascloudsdk-0.1.1/src/atlascloudsdk.egg-info/top_level.txt +2 -0
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Atlas SDK documentation
|
|
2
|
+
|
|
3
|
+
The maintained documentation is published from the `docs/` directory.
|
|
4
|
+
|
|
5
|
+
- Start with [docs/index.md](docs/index.md) for the SDK overview.
|
|
6
|
+
- Read [docs/examples.md](docs/examples.md) for runnable examples.
|
|
7
|
+
- Read [docs/production-readiness.md](docs/production-readiness.md) for current limitations and release guidance.
|
|
8
|
+
|
|
9
|
+
Build the documentation locally with:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
mkdocs serve
|
|
13
|
+
```
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.1.1] - 2026-11-02
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Established the Atlas SDK as the `atlascloudsdk` Python distribution, with
|
|
8
|
+
`from atlas import Connection` as the primary import.
|
|
9
|
+
- Documented authentication, resource discovery, and virtual machine
|
|
10
|
+
provisioning, with runnable examples and CLI guidance.
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- Set the Atlas package version to `0.1.1` for the new project.
|
|
15
|
+
- Updated the public CLI command, package metadata, documentation, and
|
|
16
|
+
examples to use Atlas naming.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Atlas
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files, to deal in the Software
|
|
7
|
+
without restriction, including without limitation the rights to use, copy,
|
|
8
|
+
modify, merge, publish, distribute, sublicense, and/or sell copies of the
|
|
9
|
+
Software, and to permit persons to whom the Software is furnished to do so,
|
|
10
|
+
subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: atlascloudsdk
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Python SDK for the Atlas API
|
|
5
|
+
Author: Atlas
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: atlas,cloud,sdk,api
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: requests>=2.32.0
|
|
22
|
+
Requires-Dist: typer>=0.12.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: pytest; extra == "dev"
|
|
25
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
26
|
+
Requires-Dist: ruff; extra == "dev"
|
|
27
|
+
Requires-Dist: mypy; extra == "dev"
|
|
28
|
+
Requires-Dist: build; extra == "dev"
|
|
29
|
+
Requires-Dist: twine; extra == "dev"
|
|
30
|
+
Requires-Dist: mkdocs-material; extra == "dev"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# Atlas Python SDK
|
|
34
|
+
|
|
35
|
+
Python SDK for managing Atlas resources through the Atlas API, including projects, networks, SSH keys, security groups, compute options, and virtual machines.
|
|
36
|
+
|
|
37
|
+
The SDK supports authenticated API connections, resource discovery, and virtual machine provisioning.
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
|
|
41
|
+
Install the Atlas Python SDK:
|
|
42
|
+
```bash
|
|
43
|
+
pip install atlascloudsdk
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use TestPyPI only when testing a pre-release build.
|
|
47
|
+
|
|
48
|
+
Python 3.10 or newer is required.
|
|
49
|
+
|
|
50
|
+
The current SDK version is `0.1.1`.
|
|
51
|
+
|
|
52
|
+
## Create a Connection
|
|
53
|
+
|
|
54
|
+
Create one authenticated connection and reuse it for API calls.
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from atlas import Connection
|
|
58
|
+
|
|
59
|
+
with Connection(
|
|
60
|
+
base_url="https://your-atlas-host",
|
|
61
|
+
username="your-username",
|
|
62
|
+
password="your-password",
|
|
63
|
+
) as client:
|
|
64
|
+
projects = client.projects.list(
|
|
65
|
+
enterprise_ref_key="ENTERPRISE_REF_KEY",
|
|
66
|
+
)
|
|
67
|
+
print(projects)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Replace the example URL and credentials with your Atlas environment details.
|
|
71
|
+
|
|
72
|
+
Applications that already have valid access and refresh tokens can initialize a connection without logging in again:
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
from atlas import Connection
|
|
76
|
+
|
|
77
|
+
client = Connection.from_tokens(
|
|
78
|
+
base_url="https://your-atlas-host",
|
|
79
|
+
access_token="ACCESS_TOKEN",
|
|
80
|
+
refresh_token="REFRESH_TOKEN",
|
|
81
|
+
)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Discover Resources
|
|
85
|
+
|
|
86
|
+
Use the reference keys returned by each API response when requesting related resources. Replace the placeholder reference keys below with valid values from your environment.
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from atlas import Connection
|
|
90
|
+
|
|
91
|
+
with Connection(
|
|
92
|
+
base_url="https://your-atlas-host",
|
|
93
|
+
username="your-username",
|
|
94
|
+
password="your-password",
|
|
95
|
+
) as client:
|
|
96
|
+
projects = client.projects.list(
|
|
97
|
+
enterprise_ref_key="ENTERPRISE_REF_KEY",
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
networks = client.networks.list(
|
|
101
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
ssh_keys = client.ssh_keys.list(
|
|
105
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
security_groups = client.security_groups.list(
|
|
109
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
operating_systems = (
|
|
113
|
+
client.compute_units.list_operating_systems()
|
|
114
|
+
)
|
|
115
|
+
|
|
116
|
+
versions = client.compute_units.list_versions(
|
|
117
|
+
os_ref_key="OS_REF_KEY",
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
flavours = client.compute_units.list_flavours(
|
|
121
|
+
version_ref_key="VERSION_REF_KEY",
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
print("Projects:", projects)
|
|
125
|
+
print("Networks:", networks)
|
|
126
|
+
print("SSH keys:", ssh_keys)
|
|
127
|
+
print("Security groups:", security_groups)
|
|
128
|
+
print("Operating systems:", operating_systems)
|
|
129
|
+
print("Versions:", versions)
|
|
130
|
+
print("Flavours:", flavours)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The API responses contain resource information, including reference keys where provided. Use the appropriate `ref_key` for subsequent operations. The SDK does not automatically select resources for you.
|
|
134
|
+
|
|
135
|
+
## Provision a Virtual Machine
|
|
136
|
+
|
|
137
|
+
To create a virtual machine, provide valid project, SSH key, network, security group, and compute flavour reference keys, along with the other required provisioning parameters.
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from atlas import Connection
|
|
141
|
+
|
|
142
|
+
with Connection(
|
|
143
|
+
base_url="https://your-atlas-host",
|
|
144
|
+
username="your-username",
|
|
145
|
+
password="your-password",
|
|
146
|
+
) as client:
|
|
147
|
+
machine_name = "training-vm"
|
|
148
|
+
|
|
149
|
+
# Confirm the return semantics of this method in your SDK version.
|
|
150
|
+
is_name_available = client.instances.validate_machine_name(
|
|
151
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
152
|
+
machine_name=machine_name,
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
if not is_name_available:
|
|
156
|
+
raise ValueError(
|
|
157
|
+
f"Machine name is already in use: {machine_name}"
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
payload = {
|
|
161
|
+
"project_ref_key": "PROJECT_REF_KEY",
|
|
162
|
+
"secret_ref_key": "SSH_SECRET_REF_KEY",
|
|
163
|
+
"network_ref_key": "NETWORK_REF_KEY",
|
|
164
|
+
"security_ref_key": "SECURITY_GROUP_REF_KEY",
|
|
165
|
+
"compute_ref_key": "FLAVOUR_REF_KEY",
|
|
166
|
+
"is_public_ip": False,
|
|
167
|
+
"bandwidth": 0,
|
|
168
|
+
"machine_name": machine_name,
|
|
169
|
+
"additional_storage": {"name": "", "size": 0},
|
|
170
|
+
"root_disk": 15,
|
|
171
|
+
"ai_services": [],
|
|
172
|
+
"platform_services": [],
|
|
173
|
+
"addons": [],
|
|
174
|
+
"license": {"name": "", "type": 0},
|
|
175
|
+
"time": 31,
|
|
176
|
+
"custom_flavour": "",
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
result = client.instances.create_vm(payload)
|
|
180
|
+
print(result)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Replace all placeholder reference keys with valid values returned by the relevant APIs. Configure the disk size, billing duration, networking, and optional services according to your requirements.
|
|
184
|
+
|
|
185
|
+
**Note:** Provisioning is asynchronous. A successful response may indicate that the request was accepted, but it does not necessarily mean the virtual machine is ready. Use the instance list or get operations to inspect the result.
|
|
186
|
+
|
|
187
|
+
## Error Handling
|
|
188
|
+
|
|
189
|
+
The SDK provides exceptions for handling API failures. The following example illustrates the pattern; use only exception classes available in your installed SDK version.
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
from atlas.exceptions import (
|
|
193
|
+
AtlasError,
|
|
194
|
+
AuthenticationError,
|
|
195
|
+
NotFoundError,
|
|
196
|
+
ValidationError,
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
try:
|
|
200
|
+
# Call an SDK resource method here.
|
|
201
|
+
pass
|
|
202
|
+
|
|
203
|
+
except AuthenticationError:
|
|
204
|
+
print("Authentication failed. Check your credentials.")
|
|
205
|
+
|
|
206
|
+
except ValidationError as error:
|
|
207
|
+
print("Validation failed:", error.details)
|
|
208
|
+
|
|
209
|
+
except NotFoundError:
|
|
210
|
+
print("Resource was not found.")
|
|
211
|
+
|
|
212
|
+
except AtlasError as error:
|
|
213
|
+
print("Status code:", error.status_code)
|
|
214
|
+
print("Details:", error.details)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Security
|
|
218
|
+
|
|
219
|
+
- Never commit passwords, access tokens, refresh tokens, private keys, or API secrets to source control.
|
|
220
|
+
- Use HTTPS for production API communication.
|
|
221
|
+
- Store credentials in environment variables or a secure secrets manager.
|
|
222
|
+
- Keep downloaded SSH private keys secure and never print or log them.
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# Atlas Python SDK
|
|
2
|
+
|
|
3
|
+
Python SDK for managing Atlas resources through the Atlas API, including projects, networks, SSH keys, security groups, compute options, and virtual machines.
|
|
4
|
+
|
|
5
|
+
The SDK supports authenticated API connections, resource discovery, and virtual machine provisioning.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
Install the Atlas Python SDK:
|
|
10
|
+
```bash
|
|
11
|
+
pip install atlascloudsdk
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Use TestPyPI only when testing a pre-release build.
|
|
15
|
+
|
|
16
|
+
Python 3.10 or newer is required.
|
|
17
|
+
|
|
18
|
+
The current SDK version is `0.1.1`.
|
|
19
|
+
|
|
20
|
+
## Create a Connection
|
|
21
|
+
|
|
22
|
+
Create one authenticated connection and reuse it for API calls.
|
|
23
|
+
|
|
24
|
+
```python
|
|
25
|
+
from atlas import Connection
|
|
26
|
+
|
|
27
|
+
with Connection(
|
|
28
|
+
base_url="https://your-atlas-host",
|
|
29
|
+
username="your-username",
|
|
30
|
+
password="your-password",
|
|
31
|
+
) as client:
|
|
32
|
+
projects = client.projects.list(
|
|
33
|
+
enterprise_ref_key="ENTERPRISE_REF_KEY",
|
|
34
|
+
)
|
|
35
|
+
print(projects)
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Replace the example URL and credentials with your Atlas environment details.
|
|
39
|
+
|
|
40
|
+
Applications that already have valid access and refresh tokens can initialize a connection without logging in again:
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
from atlas import Connection
|
|
44
|
+
|
|
45
|
+
client = Connection.from_tokens(
|
|
46
|
+
base_url="https://your-atlas-host",
|
|
47
|
+
access_token="ACCESS_TOKEN",
|
|
48
|
+
refresh_token="REFRESH_TOKEN",
|
|
49
|
+
)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Discover Resources
|
|
53
|
+
|
|
54
|
+
Use the reference keys returned by each API response when requesting related resources. Replace the placeholder reference keys below with valid values from your environment.
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from atlas import Connection
|
|
58
|
+
|
|
59
|
+
with Connection(
|
|
60
|
+
base_url="https://your-atlas-host",
|
|
61
|
+
username="your-username",
|
|
62
|
+
password="your-password",
|
|
63
|
+
) as client:
|
|
64
|
+
projects = client.projects.list(
|
|
65
|
+
enterprise_ref_key="ENTERPRISE_REF_KEY",
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
networks = client.networks.list(
|
|
69
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
ssh_keys = client.ssh_keys.list(
|
|
73
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
security_groups = client.security_groups.list(
|
|
77
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
operating_systems = (
|
|
81
|
+
client.compute_units.list_operating_systems()
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
versions = client.compute_units.list_versions(
|
|
85
|
+
os_ref_key="OS_REF_KEY",
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
flavours = client.compute_units.list_flavours(
|
|
89
|
+
version_ref_key="VERSION_REF_KEY",
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
print("Projects:", projects)
|
|
93
|
+
print("Networks:", networks)
|
|
94
|
+
print("SSH keys:", ssh_keys)
|
|
95
|
+
print("Security groups:", security_groups)
|
|
96
|
+
print("Operating systems:", operating_systems)
|
|
97
|
+
print("Versions:", versions)
|
|
98
|
+
print("Flavours:", flavours)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The API responses contain resource information, including reference keys where provided. Use the appropriate `ref_key` for subsequent operations. The SDK does not automatically select resources for you.
|
|
102
|
+
|
|
103
|
+
## Provision a Virtual Machine
|
|
104
|
+
|
|
105
|
+
To create a virtual machine, provide valid project, SSH key, network, security group, and compute flavour reference keys, along with the other required provisioning parameters.
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from atlas import Connection
|
|
109
|
+
|
|
110
|
+
with Connection(
|
|
111
|
+
base_url="https://your-atlas-host",
|
|
112
|
+
username="your-username",
|
|
113
|
+
password="your-password",
|
|
114
|
+
) as client:
|
|
115
|
+
machine_name = "training-vm"
|
|
116
|
+
|
|
117
|
+
# Confirm the return semantics of this method in your SDK version.
|
|
118
|
+
is_name_available = client.instances.validate_machine_name(
|
|
119
|
+
project_ref_key="PROJECT_REF_KEY",
|
|
120
|
+
machine_name=machine_name,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
if not is_name_available:
|
|
124
|
+
raise ValueError(
|
|
125
|
+
f"Machine name is already in use: {machine_name}"
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
payload = {
|
|
129
|
+
"project_ref_key": "PROJECT_REF_KEY",
|
|
130
|
+
"secret_ref_key": "SSH_SECRET_REF_KEY",
|
|
131
|
+
"network_ref_key": "NETWORK_REF_KEY",
|
|
132
|
+
"security_ref_key": "SECURITY_GROUP_REF_KEY",
|
|
133
|
+
"compute_ref_key": "FLAVOUR_REF_KEY",
|
|
134
|
+
"is_public_ip": False,
|
|
135
|
+
"bandwidth": 0,
|
|
136
|
+
"machine_name": machine_name,
|
|
137
|
+
"additional_storage": {"name": "", "size": 0},
|
|
138
|
+
"root_disk": 15,
|
|
139
|
+
"ai_services": [],
|
|
140
|
+
"platform_services": [],
|
|
141
|
+
"addons": [],
|
|
142
|
+
"license": {"name": "", "type": 0},
|
|
143
|
+
"time": 31,
|
|
144
|
+
"custom_flavour": "",
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
result = client.instances.create_vm(payload)
|
|
148
|
+
print(result)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Replace all placeholder reference keys with valid values returned by the relevant APIs. Configure the disk size, billing duration, networking, and optional services according to your requirements.
|
|
152
|
+
|
|
153
|
+
**Note:** Provisioning is asynchronous. A successful response may indicate that the request was accepted, but it does not necessarily mean the virtual machine is ready. Use the instance list or get operations to inspect the result.
|
|
154
|
+
|
|
155
|
+
## Error Handling
|
|
156
|
+
|
|
157
|
+
The SDK provides exceptions for handling API failures. The following example illustrates the pattern; use only exception classes available in your installed SDK version.
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
from atlas.exceptions import (
|
|
161
|
+
AtlasError,
|
|
162
|
+
AuthenticationError,
|
|
163
|
+
NotFoundError,
|
|
164
|
+
ValidationError,
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
try:
|
|
168
|
+
# Call an SDK resource method here.
|
|
169
|
+
pass
|
|
170
|
+
|
|
171
|
+
except AuthenticationError:
|
|
172
|
+
print("Authentication failed. Check your credentials.")
|
|
173
|
+
|
|
174
|
+
except ValidationError as error:
|
|
175
|
+
print("Validation failed:", error.details)
|
|
176
|
+
|
|
177
|
+
except NotFoundError:
|
|
178
|
+
print("Resource was not found.")
|
|
179
|
+
|
|
180
|
+
except AtlasError as error:
|
|
181
|
+
print("Status code:", error.status_code)
|
|
182
|
+
print("Details:", error.details)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Security
|
|
186
|
+
|
|
187
|
+
- Never commit passwords, access tokens, refresh tokens, private keys, or API secrets to source control.
|
|
188
|
+
- Use HTTPS for production API communication.
|
|
189
|
+
- Store credentials in environment variables or a secure secrets manager.
|
|
190
|
+
- Keep downloaded SSH private keys secure and never print or log them.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# SDK examples
|
|
2
|
+
|
|
3
|
+
The `examples/` directory contains small scripts for the main Atlas SDK operations. Each script uses the same basic pattern:
|
|
4
|
+
|
|
5
|
+
1. Fill in the empty configuration values at the top of the file.
|
|
6
|
+
2. Run the first operation.
|
|
7
|
+
3. Copy reference keys from the response into the next configuration value.
|
|
8
|
+
4. Uncomment and run the next operation when it is ready.
|
|
9
|
+
|
|
10
|
+
Run the examples from the repository root:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
python examples/auth.py
|
|
14
|
+
python examples/vdc.py
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The examples use a `Connection` context manager, which closes the HTTP session automatically. The authentication example uses `AuthClient` directly.
|
|
18
|
+
|
|
19
|
+
## Configuration
|
|
20
|
+
|
|
21
|
+
Every example keeps its configuration in simple variables near the top of the file:
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
BASE_URL = ""
|
|
25
|
+
USERNAME = ""
|
|
26
|
+
PASSWORD = ""
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Fill in only the values required by that example. Keep passwords, tokens, and private keys out of source control. Use HTTPS and keep TLS verification enabled in production.
|
|
30
|
+
|
|
31
|
+
## Authentication
|
|
32
|
+
|
|
33
|
+
Run `examples/auth.py` to check that the credentials work:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
python examples/auth.py
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The script prints whether access and refresh tokens were received and shows the token expiry value. It never prints the token values themselves.
|
|
40
|
+
|
|
41
|
+
For normal SDK work, `Connection` performs authentication and makes the resource managers available on the client:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from atlas import Connection
|
|
45
|
+
|
|
46
|
+
with Connection(
|
|
47
|
+
base_url=BASE_URL,
|
|
48
|
+
username=USERNAME,
|
|
49
|
+
password=PASSWORD,
|
|
50
|
+
) as client:
|
|
51
|
+
print(client.projects.list(enterprise_ref_key=ENTERPRISE_REF_KEY))
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Reference-key workflow
|
|
55
|
+
|
|
56
|
+
Most API calls need a reference key returned by an earlier call. The usual workflow is:
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
cluster -> VDC -> project -> network / SSH key / security group
|
|
60
|
+
-> operating system -> version -> flavour -> instance
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Do not guess or silently select a reference key. Read it from the API response and place it in the matching variable in the next example.
|
|
64
|
+
|
|
65
|
+
## VDCs
|
|
66
|
+
|
|
67
|
+
`examples/vdc.py` provides three separate functions:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
create_vdc()
|
|
71
|
+
get_vdc_details()
|
|
72
|
+
list_clusters()
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Start with `list_clusters()` when you need a valid `CLUSTER_REF_KEY`. Then use that key with `create_vdc()`. `get_vdc_details()` calls the VDC listing endpoint and prints the available VDC details.
|
|
76
|
+
|
|
77
|
+
The file runs `create_vdc()` by default. Uncomment the other function calls at the bottom when needed.
|
|
78
|
+
|
|
79
|
+
## Projects
|
|
80
|
+
|
|
81
|
+
`examples/projects.py` provides:
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
create_project()
|
|
85
|
+
list_projects()
|
|
86
|
+
get_project()
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Project creation requires a `VDC_REF_KEY`. Listing requires an `ENTERPRISE_REF_KEY`, and getting one project requires its `PROJECT_REF_KEY`.
|
|
90
|
+
|
|
91
|
+
Run `list_projects()` to inspect the projects belonging to an enterprise. Copy a project reference key into `PROJECT_REF_KEY` before running `get_project()`.
|
|
92
|
+
|
|
93
|
+
## Networks
|
|
94
|
+
|
|
95
|
+
`examples/networks.py` provides:
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
create_network()
|
|
99
|
+
list_networks()
|
|
100
|
+
delete_network()
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Network creation requires a project reference key and network settings:
|
|
104
|
+
|
|
105
|
+
- `NETWORK_NAME`: network name
|
|
106
|
+
- `SUBNET_NAME`: subnet name
|
|
107
|
+
- `SUBNET`: subnet value expected by the API
|
|
108
|
+
- `CIDR`: network CIDR
|
|
109
|
+
- `DNS`: a list of DNS servers
|
|
110
|
+
|
|
111
|
+
After creation, copy the network reference key into `NETWORK_REF_KEY`. Use it only when you are ready to call `delete_network()`, because deletion removes the selected network.
|
|
112
|
+
|
|
113
|
+
## SSH keys
|
|
114
|
+
|
|
115
|
+
`examples/ssh_keys.py` provides:
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
create_ssh_key()
|
|
119
|
+
list_ssh_keys()
|
|
120
|
+
download_private_key()
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Create an SSH key with `PROJECT_REF_KEY` and `SECRET_NAME`. Use `list_ssh_keys()` to inspect the keys in the project. `download_private_key()` writes the private key to `PRIVATE_KEY_OUTPUT_PATH`.
|
|
124
|
+
|
|
125
|
+
Protect the downloaded private-key file. Do not print it, commit it, or send it through an unsafe channel.
|
|
126
|
+
|
|
127
|
+
## Security groups and rules
|
|
128
|
+
|
|
129
|
+
`examples/security_groups.py` provides:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
create_security_group()
|
|
133
|
+
list_security_groups()
|
|
134
|
+
create_security_group_rule()
|
|
135
|
+
list_security_group_rules()
|
|
136
|
+
delete_security_group_rule()
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The normal order is:
|
|
140
|
+
|
|
141
|
+
1. Create a security group for a project.
|
|
142
|
+
2. Copy its reference key into `SECURITY_GROUP_REF_KEY`.
|
|
143
|
+
3. Create a rule by filling in the direction, type, destination, protocol, and optional port range.
|
|
144
|
+
4. Copy the rule reference key into `SECURITY_GROUP_RULE_REF_KEY`.
|
|
145
|
+
5. List or delete the rule as needed.
|
|
146
|
+
|
|
147
|
+
Deleting a rule is permanent for that rule, so check the reference key before running `delete_security_group_rule()`.
|
|
148
|
+
|
|
149
|
+
## Compute units
|
|
150
|
+
|
|
151
|
+
`examples/compute_units.py` follows a dependent discovery sequence:
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
list_operating_systems(client)
|
|
155
|
+
list_versions(client, OS_REF_KEY)
|
|
156
|
+
list_flavours(client, VERSION_REF_KEY)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The file opens one authenticated connection in `main()` and passes it to each function. Run the operating-system lookup first, copy an OS reference key into `OS_REF_KEY`, and uncomment `list_versions(client, OS_REF_KEY)`. Then copy a version reference key into `VERSION_REF_KEY` and uncomment `list_flavours(client, VERSION_REF_KEY)`.
|
|
160
|
+
|
|
161
|
+
The returned flavour reference key is used as `COMPUTE_REF_KEY` when creating an instance.
|
|
162
|
+
|
|
163
|
+
## Instances
|
|
164
|
+
|
|
165
|
+
`examples/instances.py` provides:
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
validate_machine_name(client)
|
|
169
|
+
create_instance(client)
|
|
170
|
+
list_instances(client)
|
|
171
|
+
get_instance(client)
|
|
172
|
+
delete_instance(client)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The instance example uses one connection in `main()`. Before creation, set these reference keys:
|
|
176
|
+
|
|
177
|
+
- `PROJECT_REF_KEY`
|
|
178
|
+
- `SSH_SECRET_REF_KEY`
|
|
179
|
+
- `NETWORK_REF_KEY`
|
|
180
|
+
- `SECURITY_GROUP_REF_KEY`
|
|
181
|
+
- `COMPUTE_REF_KEY`
|
|
182
|
+
|
|
183
|
+
The example first validates `MACHINE_NAME`. If the name is available, uncomment `create_instance(client)`. VM creation can be asynchronous, so a successful response means that the request was accepted; use `list_instances(client)` or `get_instance(client)` to inspect the result.
|
|
184
|
+
|
|
185
|
+
Copy the created instance reference key into `INSTANCE_REF_KEY` before using `get_instance(client)` or `delete_instance(client)`. Deleting an instance is destructive and should be performed only after checking the key.
|
|
186
|
+
|
|
187
|
+
## Using one connection for several operations
|
|
188
|
+
|
|
189
|
+
When several operations need to run in one process, open one connection and pass it to the functions:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
with Connection(
|
|
193
|
+
base_url=BASE_URL,
|
|
194
|
+
username=USERNAME,
|
|
195
|
+
password=PASSWORD,
|
|
196
|
+
) as client:
|
|
197
|
+
list_operating_systems(client)
|
|
198
|
+
list_versions(client, OS_REF_KEY)
|
|
199
|
+
list_flavours(client, VERSION_REF_KEY)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
This avoids creating a new authenticated session for every operation. The compute-unit and instance examples already use this pattern.
|