Skip to content

Commit 781ebac

Browse files
lennardrotherlennardrother
authored
docs: add end-user guide for instance mapping (#96)
1 parent 19fb2a5 commit 781ebac

3 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎docs/end-user-guides/hana.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ To realize the use case, you'll:
1212
- [Manage users and their privileges](/docs/crossplane-provider-hana/docs/end-user-guides/users).
1313
- [Prepare a schema](/docs/crossplane-provider-hana/docs/end-user-guides/schema).
1414
- [Manage tables](/docs/crossplane-provider-hana/docs/end-user-guides/table).
15+
- [Manage instance mappings](/docs/crossplane-provider-hana/docs/end-user-guides/instance-mapping).

‎docs/end-user-guides/instance-mapping.mdx‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Instance mapping
6+
7+
An instance mapping connects your SAP HANA Cloud database to an environment context (a Cloud Foundry org or space, or a Kyma cluster or namespace) so that applications in that context can create HDI containers or tenants in your database.
8+
9+
In this chapter, you'll learn how to manage those instance mappings declaratively using **Crossplane**.
10+
11+
:::tip Want to understand how it works under the hood?
12+
Check out the [instance mapping architecture](/docs/crossplane-provider-hana/docs/contribution-notes/instance-mapping-architecture) for details.
13+
:::
14+
15+
## 🚧 Prerequisites
16+
17+
- You've created a control plane.
18+
- You've created a [HANA Cloud instance](/docs/crossplane-provider-hana/docs/end-user-guides/setup).
19+
- You've setup the [HANA Provider](/docs/crossplane-provider-hana/docs/end-user-guides/setup#install-provider).
20+
- Cloud Foundry: You've created an [org and space](/docs/crossplane-provider-cloudfoundry/docs/end-user-guides/configure-provider-cf#import-organization-).
21+
- Kyma: _Coming soon ..._
22+
23+
## Get access to the admin API
24+
25+
Create an `Entitlement`, `ServiceInstance`, and `ServiceBinding` for the `hana-cloud` offering with plan `admin-api-access`.
26+
27+
```yaml title="hana-admin-api.yaml"
28+
apiVersion: account.btp.sap.crossplane.io/v1alpha1
29+
kind: Entitlement
30+
metadata:
31+
name: hana-cloud-api-entitlement
32+
spec:
33+
forProvider:
34+
serviceName: hana-cloud
35+
servicePlanName: admin-api-access
36+
servicePlanUniqueIdentifier: hana-cloud-admin-api-access
37+
enable: true
38+
subaccountRef:
39+
name: my-subaccount
40+
---
41+
apiVersion: account.btp.sap.crossplane.io/v1alpha1
42+
kind: ServiceInstance
43+
metadata:
44+
name: hana-api
45+
spec:
46+
forProvider:
47+
name: hana-api
48+
offeringName: hana-cloud
49+
planName: admin-api-access
50+
serviceManagerRef:
51+
name: my-subaccount-service-manager
52+
subaccountRef:
53+
name: my-subaccount
54+
parameters:
55+
technicalUser: true
56+
---
57+
apiVersion: account.btp.sap.crossplane.io/v1alpha1
58+
kind: ServiceBinding
59+
metadata:
60+
name: hana-api-binding
61+
spec:
62+
forProvider:
63+
name: hana-api-binding
64+
serviceInstanceRef:
65+
name: hana-api
66+
subaccountRef:
67+
name: my-subaccount
68+
writeConnectionSecretToRef:
69+
namespace: default
70+
name: hana-api-binding-secret
71+
```
72+
73+
Apply the resources to your control plane:
74+
75+
```shell title="Run in terminal"
76+
kubectl create -f hana-admin-api.yaml
77+
```
78+
79+
The `ServiceBinding` creates the secret in a different format than the HANA provider expects. Until this is solved as part of [#88](https://github.com/SAP/crossplane-provider-hana/issues/88), create the secret manually.
80+
Replace `<baseurl>` with the base URL and `<uaa>` with the UAA object from the secret created by the `ServiceBinding` above.
81+
82+
```yaml title="hana-api-secret.yaml" {8}
83+
apiVersion: v1
84+
kind: Secret
85+
metadata:
86+
name: hana-api-secret
87+
namespace: default
88+
type: Opaque
89+
data:
90+
credentials: '{"baseurl":"{{<baseurl>}}","uaa":{{<uaa>}}}'
91+
```
92+
93+
Apply the secret to your control plane:
94+
95+
```shell title="Run in terminal"
96+
kubectl create -f hana-api-secret.yaml
97+
```
98+
99+
## Create an instance mapping (Cloud Foundry)
100+
101+
Begin by [installing kro](https://kro.run/docs/getting-started/Installation) in your control plane.
102+
103+
Next, create a `ResourceGraphDefinition` (RGD) for a Cloud Foundry HANA instance mapping.
104+
105+
```yaml title="cf-hana-instance-mapping-rgd.yaml"
106+
apiVersion: kro.run/v1alpha1
107+
kind: ResourceGraphDefinition
108+
metadata:
109+
name: cf-hana-instance-mapping
110+
spec:
111+
schema:
112+
apiVersion: v1alpha1
113+
kind: CfHanaInstanceMapping
114+
spec:
115+
serviceInstanceRef: string
116+
orgRef: string
117+
spaceRef: string
118+
resources:
119+
- id: serviceInstance
120+
externalRef:
121+
apiVersion: account.btp.sap.crossplane.io/v1alpha1
122+
kind: ServiceInstance
123+
metadata:
124+
name: ${schema.spec.serviceInstanceRef}
125+
- id: org
126+
externalRef:
127+
apiVersion: cloudfoundry.crossplane.io/v1alpha1
128+
kind: Organization
129+
metadata:
130+
name: ${schema.spec.orgRef}
131+
- id: space
132+
externalRef:
133+
apiVersion: cloudfoundry.crossplane.io/v1alpha1
134+
kind: Space
135+
metadata:
136+
name: ${schema.spec.spaceRef}
137+
- id: instanceMapping
138+
template:
139+
apiVersion: inventory.hana.orchestrate.cloud.sap/v1alpha1
140+
kind: InstanceMapping
141+
metadata:
142+
name: ${schema.metadata.name}
143+
spec:
144+
forProvider:
145+
platform: cloudfoundry
146+
serviceInstanceID: ${serviceInstance.status.atProvider.id}
147+
primaryID: ${org.status.atProvider.id}
148+
secondaryID: ${space.status.atProvider.id}
149+
adminCredentialsSecretRef:
150+
name: hana-api-secret
151+
namespace: default
152+
key: credentials
153+
```
154+
155+
<button onClick={() => window.open("https://doc.crds.dev/github.com/SAP/crossplane-provider-hana/inventory.hana.orchestrate.cloud.sap/InstanceMapping/v1alpha1@v0.1.1", "_blank")} className='button button--secondary'>See full CRD reference</button>
156+
<br/><br/>
157+
158+
:::tip Want to map to all spaces in an organization?
159+
To map to all spaces in an organization instead of a specific space, omit the `spaceRef` from the schema and the `secondaryID` from the `InstanceMapping` template.
160+
:::
161+
162+
Apply the RGD to your control plane:
163+
164+
```shell title="Run in terminal"
165+
kubectl create -f cf-hana-instance-mapping-rgd.yaml
166+
```
167+
168+
Finally, create a Cloud Foundry HANA instance mapping.
169+
170+
```yaml title="cf-hana-instance-mapping.yaml"
171+
apiVersion: kro.run/v1alpha1
172+
kind: CfHanaInstanceMapping
173+
metadata:
174+
name: cf-hana-instance-mapping
175+
spec:
176+
serviceInstanceRef: my-hana # name of BTP Provider ServiceInstance custom resource
177+
orgRef: my-org # name of CF Provider Organization custom resource
178+
spaceRef: my-space # name of CF Provider Space custom resource
179+
```
180+
181+
Apply it to your control plane:
182+
183+
```shell title="Run in terminal"
184+
kubectl create -f cf-hana-instance-mapping.yaml
185+
```
186+
187+
Your SAP HANA Cloud database is now mapped to the Cloud Foundry space and applications in that space can create HDI containers in your database.
188+
189+
If you [have a subscription to SAP HANA Cloud Administration Tools](/docs/crossplane-provider-btp/docs/end-user-guides/services/create-services#subscription), you can verify the creation of the instance mapping in the configuration of your SAP HANA Cloud instance:
190+
191+
![Instance mapping in SAP HANA Cloud Administration Tools](/img/instance-mapping.png)
192+
193+
## Create an instance mapping (Kyma)
194+
195+
_Coming soon ..._
196+
197+
## ⁉ FAQs
198+
199+
No FAQs yet. Got a question? Reach out to us and help us build this section.

‎docs/img/instance-mapping.png‎

1.22 MB
Loading

0 commit comments

Comments
 (0)