Skip to content

Commit 6a13d96

Browse files
RichardSmedleyRichardSmedley
committed
New section landing pages
1 parent c96d364 commit 6a13d96

2 files changed

Lines changed: 280 additions & 0 deletions

File tree

‎modules/concept-docs/pages/management-api.adoc‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
= Managing Couchbase Clusters from the SDK
2+
:page-aliases: buckets-and-clusters.adoc
3+
:page-toclevels: 2
4+
:description: Cluster management from the SDK.
5+
6+
7+
8+
[abstract]
9+
{description}
10+
11+
12+
The Couchbase {name-sdk} has a management API to provision clusters.
13+
This is not the only programmatic way to deploy Couchbase, and you may wish to look at
14+
xref:cloud:terraform:index.adoc[Terraform] for Capella, or some of our command line tools.
15+
16+
17+
== Buckets and Clusters
18+
19+
include::{version-common}@sdk:shared:partial$clusters-buckets.adoc[tag=management]
20+
21+
// ...
22+
Management operations in the Java SDK may be performed through several interfaces depending on the object:
23+
24+
== Creating and Removing Buckets
25+
26+
To create or delete a bucket, call the bucket manager with the `buckets()` call on the cluster:
27+
28+
[source,java]
29+
----
30+
Cluster cluster = Cluster.connect("127.0.0.1", "user", "123456");
31+
BucketManager manager = cluster.buckets();
32+
manager.createBucket(bucketSettings);
33+
----
34+
35+
// The `BucketSettings` can be created via a builder, [.api]`DefaultBucketSettings.builder()`.
36+
This class is also used to expose information about an existing bucket (`manager.getBucket(string)`) or to update an existing bucket (`manager.updateBucket(bucketSettings)`).
37+
38+
The default Collection & Default Scope will be used automatically.
39+
40+
41+
42+
43+
44+
45+
// Collections & Scopes
46+
////
47+
48+
The Collections feature in Couchbase Server 7.0 is fully implemented in the Scala SDK version 1.2.
49+
50+
Please see the xref:{version-server}@server:learn:data/scopes-and-collections.adoc[Scopes and Collections page] in the Server docs.
51+
52+
== Using Collections & Scopes
53+
54+
Access a non-default collection, in the default scope, with:
55+
56+
[source,scala]
57+
----
58+
include::example$CollectionsExample.scala[tag=collections_1,indent=0]
59+
----
60+
61+
And for a non-default scope:
62+
[source,scala]
63+
----
64+
include::example$CollectionsExample.scala[tag=collections_2,indent=0]
65+
----
66+
67+
68+
== Further Reading
69+
70+
To see Collections in action, take a look at our xref:howtos:working-with-collections.adoc[Collections-enabled Travel Sample page].
71+
////
72+
73+
74+
75+
76+
77+
== User Management
78+
79+
include::{version-common}@sdk:pages:partial$user-management.adoc[]
80+
81+
82+
The SDK lets you programmatically create _users_, assign them _roles_ and associated _privileges_, and remove them from the system.
83+
84+
This is an overview of the user management API's capabilities.
85+
For a practical look at using it, see xref:howtos:sdk-user-management-example.adoc[Sample Code].
86+
87+
=== Creating a User
88+
89+
The syntax required for creating a user varies according to language, and is covered for each SDK in the management documentation.
90+
The basic form is as follows:
91+
92+
----
93+
boolean upsertUser (String userid, UserSettings settings)
94+
----
95+
96+
The method *upsertUser* creates a user and adds the user to the Couchbase Cluster.
97+
The user will subsequently be visible in the *Security* panel of the Couchbase Web Console.
98+
Note that successful user-addition results in a user _locally_ defined, with _username_ and _password_ stored on Couchbase Server: _external_ users (whose credentials reside on a network-available server, possibly accessed by means of LDAP) should not be created by this SDK method.
99+
If the local user created by *upsertUser* already exists, the previous definition is overwritten.
100+
101+
The method takes two arguments.
102+
The first, a _String_ is the user ID of the user to be created: for example, `johnsmith0325`, or `user734`.
103+
This must be specified.
104+
105+
The second is a _UserSettings_ object.
106+
This takes the following form:
107+
108+
----
109+
UserSettings {
110+
String password;
111+
String name;
112+
Role[] roles;
113+
}
114+
----
115+
116+
The object contains three data-members.
117+
The first is a _String_ that specifies the user's password: this must be provided.
118+
The second is a _String_ that specifies the user's name (for example, `John Smith`): this is optional, and so may be omitted.
119+
The third is an array of _Role_ objects: this must be specified.
120+
Each _Role_ object takes the following form:
121+
122+
----
123+
Role {
124+
String role;
125+
String bucket_name;
126+
}
127+
----
128+
129+
The object's two data-members are both _Strings_, and must both be specified.
130+
The _String_ specified as the role must correspond to a role supported by Couchbase Server.
131+
The _String_ specified as the bucket_name must either correspond to a bucket currently defined on Couchbase Server; or be the asterisk character (_*_), meaning _all buckets_.
132+
133+
The method returns a _boolean_, which is `true` if the operation is successful, otherwise `false`.
134+
// end::creating_a_user[]
135+
136+
[#listing_users]
137+
// tag::listing_users[]
138+
=== Listing Users
139+
140+
The basic form of the method used to return currently defined users is as follows:
141+
142+
----
143+
List<User> getUsers()
144+
----
145+
146+
The method returns a list of _User_ objects, each of which takes the following form:
147+
148+
----
149+
User {
150+
String name;
151+
String id;
152+
String domain;
153+
Role[] roles;
154+
}
155+
----
156+
157+
The name is the full name of the user.
158+
The id is the user's ID.
159+
The domain is either `local` or `external`.
160+
Each Role object in the Role-array has the form already described above, in _Creating a User_.
161+
162+
163+
=== Getting a User
164+
165+
The basic form of the method used to return an already defined user is as follows:
166+
167+
----
168+
User getUser (String userid)
169+
----
170+
171+
The method returns a _User_ object, which takes the following form:
172+
173+
----
174+
User {
175+
String name;
176+
String id;
177+
String domain;
178+
Role[] roles;
179+
}
180+
----
181+
182+
The name is the full name of the user.
183+
The id is the user's ID.
184+
The domain is either `local` or `external`.
185+
Each Role object in the Role-array has the form described above, in _Creating a User_.
186+
187+
188+
=== Removing a User
189+
190+
The basic form of the method used to remove users is as follows:
191+
192+
----
193+
boolean removeUser (String userid)
194+
----
195+
196+
The method's sole argument is the id of the user to be removed from the system, specified as a _String_.
197+
The method returns a _boolean_, whose value is `true` if the operation is successful, otherwise `false`.
198+
199+
200+
201+
// == Further Information
202+
203+
// For SDK implementation of the API, see xref:howtos:sdk-user-management-example.adoc[Sample Code].

‎modules/project-docs/pages/deployment.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
= Deployment
2+
:page-toclevels: 2
3+
:description: Transition from dev environment to prod, and keep up with the latest fixes.
4+
5+
6+
// Note to editors
7+
//
8+
// This page pulls in content from -sdk-common-
9+
// and code samples from -example-dir-
10+
//
11+
// It can be seen built at wwww.
12+
13+
[abstract]
14+
{description}
15+
16+
17+
18+
19+
20+
21+
22+
One of Couchbase's strengths is speedy response, so deployment of apps should be in the same region as the Server -- whether Capella, or your own self-managed cluster.
23+
24+
We always recommend the xref::sdk-release-notes.adoc#latest-release[latest version] of the SDK.
25+
This not only contains the latest security updates and bug fixes, but will be compatible with the latest Couchbase Server release
26+
(note, Capella always runs a recent version of Couchbase Server).
27+
28+
Before deploying, take note of any xref:compatibility.adoc[compatibility] issues for the language platform and underlying OS.
29+
The xref:sdk-full-installation.adoc[full installation guide] should cover any special cases for all supported environments.
30+
31+
32+
== Development & Testing Environments
33+
34+
During development, some shortcuts are taken to get up and running which would not be acceptable during deployment.
35+
These include use of administrator permissions, connecting from your laptop instead of a secure app server, and even disabling certificate verification for TLS.
36+
Testing environments may also differ from deployment.
37+
38+
The {name-sdk} docs note whenever a shortcut is being taken, but here is a non-exhaustive list of those development practices which should not be carried over to production deployments:
39+
40+
* Over-priveleged access
41+
* Geographical separation of app server and database
42+
* Skipping certificate verification
43+
// * more
44+
45+
The best way to accommodate developing an application that is to be deployed to production is to use the platform's default approach for configuration files.
46+
47+
For the Java SDK, that is to keep a separate properties file for your development and production environments.
48+
49+
50+
51+
52+
== Migration
53+
54+
This section also contains information on xref:migrating-sdk-code-to-3.n.adoc[migrating from the previous major version of the SDK API].
55+
56+
// :migration-link: for 4.x pages??
57+
58+
59+
== Further Reading
60+
61+
* Integrate Couchbase with your data ecosystem:
62+
** xref:project-docs:third-party-integrations.adoc[SDK Integrations]
63+
** xref:server:develop:integrations.adoc[Integrations across Couchbase]
64+
* xref:project-docs:get-involved.adoc[Contribute to the SDK]
65+
66+
=== Deploying Couchbase Server
67+
68+
* xref:cloud::index.adoc[Capella] -- Database as a Service
69+
* xref:{version-server}@server:install:get-started.adoc[Self-managed Couchbase Server]:
70+
** xref:{version-server}@server:install:getting-started-docker.adoc[Docker Install]
71+
** xref:operator::overview.adoc[Couchbase Autonomous Operator]
72+
*** xref:operator::install-kubernetes.adoc[Kubernetes]
73+
*** xref:operator::install-openshift.adoc[Openshift]
74+
** xref:{version-server}server:cloud:couchbase-cloud-deployment.adoc[Cloud Marketplace]:
75+
*** xref:{version-server}@server:cloud:couchbase-aws-marketplace.adoc[AWS Marketplace]
76+
*** xref:{version-server}@server:cloud:couchbase-azure-marketplace.adoc[Azure Marketplace]
77+
*** xref:{version-server}@server:cloud:couchbase-gcp-cloud-launcher.adoc[GCP Marketplace]

0 commit comments

Comments
 (0)