forked from Comcast/cmb
-
Notifications
You must be signed in to change notification settings - Fork 0
/
FAQ.txt
169 lines (107 loc) · 8.35 KB
/
FAQ.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
--------------------------------------------------------------------------------------------
- FREQUENTLY ASKED QUESTIONS
--------------------------------------------------------------------------------------------
0. I HAVE A QUESTION / FEATURE ENHANCEMENT REQUEST / BUG REPORT - WHAT DO I DO?
Post a question in the CMB User Forum at https://groups.google.com/forum/#!forum/cmb-user-forum
1. I just installed CMB. When I try to call CQS APIs I get Redis exceptions such as
'unknown command 'EVALSHA'' exceptions.
You must use Redis version 2.6 or higher. An easy way to check your Redis version is
redis-cli --version
2. I installed CMB over a 3-node Cassandra ring. As soon as a single Cassandra node fails
CMB stops working with Cassandra exceptions such as 'TokenRangeOfflineException'.
Isn't the whole point of using Cassandra fault tolerance?
Yes! But, by default the CMB keyspaces are created with default replication factor RF=1. While
this works great for single-node POC-style deployments, it's no good for larger Cassandra
rings where you want to use RF=3 or higher to tolerate loss of a at least one Cassandra node.
You can find an example showing how to create keyspaces with RF=3 in a commented out
section at the top of schema/cassandra_1.2.schema:
create keyspace CNS with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy' and strategy_options = {replication_factor:3};
create keyspace CQS with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy' and strategy_options = {replication_factor:3};
create keyspace CMB with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy' and strategy_options = {replication_factor:3};
3. I find installing CMB, Redis and Cassandra way too cumbersome. I just want to try out a simple
single node full-stack CMB deployment and play with it a little before getting serious
about CMB. What can I do?
You can use our single-node Vagrant version which will bootstrap everything you need to get
going in a single VM, including Java, Cassandra, Redis and CMB. Simply do
> cd packaging/vagrant/cmbbase
> vagrant up
and after a few minutes you will end up with a running version of CMB. The supplied bootstrap.sh
script may also be helpful in understanding what it takes to install CMB manually yourself.
With a little bit of work you can even turn this into a multi-node version using the Vagrant
file in packaging/vagrant/cmbcluster.
4. Help, I can't publish messages from a CNS topic into a CQS queue!
There are several reasons why the CNS service may not be working properly. You should try using
the service manually via Web UI first and methodically follow these steps:
Before trying to use CNS you should make sure CQS is working by creating a queue and by sending,
receiving and deleting a test message. You should do this because CNS builds on top of CQS and
thus without a working CQS service there is no CNS service.
If CQS is working you should try publishing to an HTTP endpoint next. If you don't have a HTTP
endpoint you can use the CMB built-in endpoint at
http://localhost:6059/Endpoint/recv/mytestendpoint
for testing purposes. After publishing a message on the topic check if it has arrived at
http://localhost:6059/Endpoint/list
If CQS is working and you can publish to HTTP enpoints, then try publishing into a CQS queue.
There are a few common pitfalls which are detailed below but if you use the same CMB user for creating
the queue and the topic it should be pretty straight-forward. Just make sure to choose "CQS" as
the protocol when publishing into a CQS queue (not "SQS").
5. How do I subscribe a CQS queue to a CNS topic? And what about subscriptions "pending confirmation"?
When subscribing a CQS queue to a CNS topic you must choose "CQS" as the protocol, not "SQS"!
Notice that when using the AWS Java SDK this means you have to write something like
String queueUrl = createQueueResult.getQueueUrl();
String queueArn = com.comcast.cqs.util.Util.getArnForAbsoluteQueueUrl(queueUrl);
amazonSNSClient.subscribe(createTopicResult.getTopicArn(), "cqs", queueArn);
instead of
Topics.subscribeQueue(amazonSNSClient, amazonSQSClient, createTopicResult.getTopicArn(), createQueueResult.getQueueUrl());
and accordingly when using other language bindings of the AWS SDK.
If both, the CQS queue and the CNS topic are owned (created) by the same user, then you are done
at this point. All messages you publish on the CNS topic will be published as messages into the
CQS queue. You will be able to see the subscription as a confirmed subscription with a valid arn
in the CMB Web UI.
If, however, the CQS queue and the CNS topic have been created by different CMB users, then the
subscription is not in effect immediately but rather in a "pending confirmation" state. Check the
queue for messages and you will find a message with a confirmation request sent by CNS when the
subscription was created. This message contains a fully qualified URL with a one-time-use token.
Once you hit that link the subscription will be confirmed and from then on any message published
on the topic will be published into the queue just like before. The idea behind confirmations is
to avoid inadvertently spamming other user's queues with messages. By asking for a confirmation
both parties can be sure to agree on the subscription.
6. I find dealing with confirmations cumbersome - is there anything I can do to simplify this?
Absolutely - either use the same CMB user for all your CMB needs and rely on subscriptions
being auto-confirmed, or, if that's not an option set
cmb.cns.requireSubscriptionConfirmation=false
in cmb.properties and restart the service. With this configuration change subscriptions will
always be auto-confirmed even if topic and queue are owned by different users.
Note: Changing requireSubscriptionConfirmation to false only applies to future subscriptions.
It does no auto-confirm already existing subscriptions in "pending confirmation" state. These still
have to be confirmed (or deleted).
7. Can I subscribe an AWS SQS queue to a CNS topic?
Yes, you can even subscribe an AWS SQS queue to a CNS topic and thus publish from a CNS
topic directly into a AWS SQS queue. If you want to do this be sure to set you AWS credentials
in cmb.properties and restart the service.
aws.access.key=
aws.access.secret=
Currently you can only set a single AWS key and secret globally in cmb.properties which will then
be shared by all CMB users.
8. Do all CMB requests have to be signed?
No, in fact by default the signature verification feature is turned off assuming you are operating
on a trusted network behind a firewall. If you want to enforce signature validation set
cmb.enableSignatureAuth=true
in cmb.properties and restart the service. CMB supports signature validation for AWS signatures
version 1, 2 and 4.
9. Do all API calls have to be POST requests or can I use HTTP GET requests as well?
Both POST and GET are supported. GET requests make testing via browser a lot easier. If you
would like to disable GET requests you can do so by setting
cmb.allowGetRequest=false
in cmb.properties and restarting the service.
10. Does CMB support the ContentType=JSON parameter?
No, unfortunately not yet. By default AWS SQS and SNS respond with XML and so does CMB. There is
an undocumented parameter ContentType=JSON you can use in AWS to get JSON responses instead but
this is not implemented in CMB. We are aware that some client libraries (like Python's boto)
rely on this. As a result you can use boto for interacting with CQS but not CNS. You can also
patch boto.
https://github.com/boto/boto/pull/827
11. Can I use the boto client library, or, for that matter AWS client library xyz to interact with CMB?
CMB is primarily developed with and tested for the AWS Java SDK. People have also successfully
used the nodejs client library and to some degree boto can be used (see 7 above). Of course you
can also hand craft your API calls and "curl" them. This option is particularly viable with
signature validation turned off.