1 # Licensed to the Apache Software Foundation (ASF) under one or more
2 # contributor license agreements. See the NOTICE file distributed with
3 # this work for additional information regarding copyright ownership.
4 # The ASF licenses this file to You under the Apache License, Version 2.0
5 # (the "License"); you may not use this file except in compliance with
6 # the License. You may obtain a copy of the License at
8 # http://www.apache.org/licenses/LICENSE-2.0
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
23 clearwater_operation_dependencies: &CLEARWATER_OPERATION_DEPENDENCIES
24 - "ssh.user > { get_property: [ HOST, host, ssh.user ] }"
25 - "ssh.password > { get_property: [ HOST, host, ssh.password ] }"
26 - "ssh.address > { get_attribute: [ HOST, public_address ] }"
27 - "ssh.use_sudo > true"
31 clearwater.Configuration:
32 derived_from: tosca.policies.Root
36 The domain name for SIP addresses, for example if its "example.com" then a SIP address
37 could be "6505550243@example.com".
39 geographically_redundant:
41 Enable a geographically redundant deployment.
43 See: http://clearwater.readthedocs.io/en/stable/Geographic_redundancy.html
48 Used by geographically redundant deployments.
53 Used for registration via Ellis.
60 Clearwater container capability.
61 derived_from: tosca.capabilities.Container
69 max_log_directory_size:
70 type: scalar-unit.size
71 default: 0 B # 0 means no max size
72 reduce_cassandra_mem_usage:
76 # http://clearwater.readthedocs.io/en/stable/Clearwater_IP_Port_Usage.html
80 clearwater.Endpoint.SIP.Upstream:
81 derived_from: tosca.capabilities.Endpoint
87 type: tosca.datatypes.network.PortDef
90 clearwater.Endpoint.SIP.Upstream.Secure:
91 derived_from: tosca.capabilities.Endpoint
97 type: tosca.datatypes.network.PortDef
103 clearwater.Endpoint.SIP.Proxy:
104 derived_from: tosca.capabilities.Endpoint
110 type: tosca.datatypes.network.PortDef
113 clearwater.Endpoint.SIP.Public:
114 derived_from: tosca.capabilities.Endpoint.Public
120 type: tosca.datatypes.network.PortDef
123 clearwater.Endpoint.SIP.Public.Secure:
124 derived_from: tosca.capabilities.Endpoint.Public
130 type: tosca.datatypes.network.PortDef
138 clearwater.Endpoint.STUN:
139 derived_from: tosca.capabilities.Endpoint
145 type: tosca.datatypes.network.PortDef
150 clearwater.Endpoint.Diameter.HSS:
152 In shared_config: hs_listen_port
153 derived_from: tosca.capabilities.Endpoint
159 type: tosca.datatypes.network.PortDef
162 clearwater.Endpoint.Diameter.CTF:
164 In shared_config: ralf_listen_port
165 derived_from: tosca.capabilities.Endpoint
171 type: tosca.datatypes.network.PortDef
174 # Management endpoints
176 clearwater.Endpoint.Management.Homer:
177 derived_from: ims.interfaces.HTTP
180 type: tosca.datatypes.network.PortDef
183 clearwater.Endpoint.Management.Homestead:
184 derived_from: ims.interfaces.HTTP
187 type: tosca.datatypes.network.PortDef
190 clearwater.Endpoint.Management.Homestead.Provisioning:
192 In shared_config: homestead_provisioning_port
193 derived_from: ims.interfaces.HTTP
196 type: tosca.datatypes.network.PortDef
199 clearwater.Endpoint.Management.Sprout:
200 derived_from: ims.interfaces.HTTP
203 type: tosca.datatypes.network.PortDef
206 clearwater.Endpoint.Management.Ralf:
207 derived_from: ims.interfaces.HTTP
210 type: tosca.datatypes.network.PortDef
211 default: 9888 # note: some documentation shows 10888
215 clearwater.Endpoint.Public.Web:
216 derived_from: tosca.capabilities.Endpoint.Public
222 type: tosca.datatypes.network.PortDef
228 clearwater.Endpoint.Public.Web.Secure:
229 derived_from: tosca.capabilities.Endpoint.Public
235 type: tosca.datatypes.network.PortDef
246 clearwater.Endpoint.Chronos:
247 derived_from: tosca.capabilities.Endpoint
250 type: tosca.datatypes.network.PortDef
253 clearwater.Endpoint.Memcached:
254 derived_from: tosca.capabilities.Endpoint
257 type: tosca.datatypes.network.PortDef
260 clearwater.Endpoint.Astaire:
261 derived_from: tosca.capabilities.Endpoint
264 type: tosca.datatypes.network.PortDef
272 - pattern: '^\d{10}$'
276 # http://clearwater.readthedocs.io/en/stable/Clearwater_Architecture.html
278 clearwater.SoftwareComponent:
280 Clearwater software components must be installed in a Clearwater-capable compute node.
281 derived_from: tosca.nodes.SoftwareComponent
284 capability: clearwater.Container
285 relationship: tosca.relationships.HostedOn
289 Clearwater edge proxy.
291 The Bono nodes form a horizontally scalable SIP edge proxy providing both a SIP IMS Gm
292 compliant interface and a WebRTC interface to clients. Client connections are load balanced
293 across the nodes. The Bono node provides the anchor point for the client's connection to the
294 Clearwater system, including support for various NAT traversal mechanisms. A client is
295 therefore anchored to a particular Bono node for the duration of its registration, but can
296 move to another Bono node if the connection or client fails.
298 Clients can connect to Bono using SIP/UDP or SIP/TCP. Bono supports any WebRTC client that
299 performs call setup signaling using SIP over WebSocket.
301 Alternatively, Clearwater can be deployed with a third party P-CSCF or Session Border
302 Controller implementing P-CSCF. In this case Bono nodes are not required.
303 derived_from: clearwater.SoftwareComponent
305 p-cscf: ims.functions.P-CSCF
306 gm: ims.interfaces.Gm
307 sip_endpoint: clearwater.Endpoint.SIP.Public
308 sip_secure_endpoint: clearwater.Endpoint.SIP.Public.Secure
309 sip_proxy: clearwater.Endpoint.SIP.Proxy # open to Sprout
310 stun_endoint: clearwater.Endpoint.STUN
313 capability: clearwater.Endpoint.SIP.Upstream
314 occurrences: [ 0, UNBOUNDED ]
315 - sip_secure_downstream:
316 capability: clearwater.Endpoint.SIP.Upstream.Secure
317 occurrences: [ 0, UNBOUNDED ]
318 - ralf: # for billable events
319 capability: clearwater.Endpoint.Management.Ralf
320 occurrences: [ 0, 1 ]
323 type: tosca.interfaces.node.lifecycle.Standard
326 primary: scripts/bono/create.sh
327 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
330 primary: scripts/bono/delete.sh
331 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
335 Clearwater SIP router.
337 The Sprout nodes act as a horizontally scalable, combined SIP registrar and authoritative
338 routing proxy, and handle client authentication and the ISC interface to application servers.
339 The Sprout nodes also contain the in-built MMTEL application server. SIP transactions are load
340 balanced across the Sprout cluster, so there is no long-lived association between a client and
341 a particular Sprout node. Sprout does not store any long-lived data itself and instead uses
342 web service interfaces to Homestead and Homer to retrieve HSS configuration such as
343 authentication data/user profiles and MMTEL service settings APIs to Vellum for storing
344 subscriber registration data and for running timers.
346 Sprout is where the bulk of the I-CSCF and S-CSCF function resides, with the remainder
347 provided by Dime (and backed by the long-lived data stores on Vellum).
348 derived_from: clearwater.SoftwareComponent
350 sip_endpoint: clearwater.Endpoint.SIP.Upstream # open to Bono
351 sip_secure_endpoint: clearwater.Endpoint.SIP.Upstream.Secure # open to Bono
352 management_endpoint: clearwater.Endpoint.Management.Sprout
354 type: tosca.capabilities.Container
355 valid_source_types: [ clearwater.Memento ]
357 # cyclical: see ARIA-327
359 # capability: clearwater.Endpoint.SIP.Proxy
360 # occurrences: [ 0, UNBOUNDED ]
361 - homer: # for subscriber profiles
362 capability: clearwater.Endpoint.Management.Homer
363 - ralf: # for billable events
364 capability: clearwater.Endpoint.Management.Ralf
365 occurrences: [ 0, 1 ]
367 capability: clearwater.Endpoint.Chronos
368 node: clearwater.Vellum
370 capability: clearwater.Endpoint.Astaire
371 node: clearwater.Vellum
374 type: tosca.interfaces.node.lifecycle.Standard
377 primary: scripts/sprout/create.sh
378 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
381 primary: scripts/sprout/delete.sh
382 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
385 derived_from: tosca.nodes.Root
387 sip-as: ims.functions.SIP-AS
388 web_secure_endpoint: clearwater.Endpoint.Public.Web.Secure
391 capability: tosca.capabilities.Container
392 node: clearwater.Sprout
394 capability: cassandra.Endpoint.Thrift
395 node: clearwater.Vellum
398 type: tosca.interfaces.node.lifecycle.Standard
401 primary: scripts/memento/create.sh
402 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
405 primary: scripts/memento/delete.sh
406 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
410 Clearwater Diameter gateway.
412 Dime nodes run Clearwater's Homestead and Ralf components.
413 derived_from: clearwater.SoftwareComponent
416 type: tosca.capabilities.Container
417 valid_source_types: [ clearwater.DimeSoftwareComponent ]
420 type: tosca.interfaces.node.lifecycle.Standard
423 primary: scripts/dime/create.sh
424 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
427 primary: scripts/dime/delete.sh
428 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
430 clearwater.DimeSoftwareComponent:
432 Base type for Dime software components.
433 derived_from: clearwater.SoftwareComponent
436 capability: tosca.capabilities.Container
437 node: clearwater.Dime
439 clearwater.Homestead:
441 Clearwater HSS cache.
443 Homestead provides a web services interface to Sprout for retrieving authentication
444 credentials and user profile information. It can either master the data (in which case it
445 exposes a web services provisioning interface) or can pull the data from an IMS compliant HSS
446 over the Cx interface. The Homestead nodes themselves are stateless - the mastered / cached
447 subscriber data is all stored on Vellum (via Cassandra's Thrift interface).
449 In the IMS architecture, the HSS mirror function is considered to be part of the I-CSCF and
450 S-CSCF components, so in Clearwater I-CSCF and S-CSCF function is implemented with a
451 combination of Sprout and Dime clusters.
452 derived_from: clearwater.DimeSoftwareComponent
454 hss: ims.functions.HSS
455 cx: ims.interfaces.Cx
456 diameter_endpoint: clearwater.Endpoint.Diameter.HSS
457 management_endpoint: clearwater.Endpoint.Management.Homestead # open to Ellis
458 provisioning_management_endpoint: clearwater.Endpoint.Management.Homestead.Provisioning # open to Ellis
461 capability: cassandra.Endpoint.Thrift
462 node: clearwater.Vellum
465 type: tosca.interfaces.node.lifecycle.Standard
468 primary: scripts/homestead/create.sh
469 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
472 primary: scripts/homestead/delete.sh
473 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
479 Ralf provides an HTTP API that both Bono and Sprout can use to report billable events that
480 should be passed to the CDF (Charging Data Function) over the Rf billing interface. Ralf is
481 stateless, using Vellum to maintain the long lived session state and run the timers necessary
482 to enable it to conform to the Rf protocol.
483 derived_from: clearwater.DimeSoftwareComponent
485 ctf: ims.functions.CTF
486 rf: ims.interfaces.Rf
487 diameter_endpoint: clearwater.Endpoint.Diameter.CTF
488 management_endpoint: clearwater.Endpoint.Management.Ralf # open to Sprout, Bono, Vellum
491 capability: clearwater.Endpoint.Chronos
492 node: clearwater.Vellum
494 capability: clearwater.Endpoint.Astaire
495 node: clearwater.Vellum
498 type: tosca.interfaces.node.lifecycle.Standard
501 primary: scripts/ralf/create.sh
502 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
505 primary: scripts/ralf/delete.sh
506 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
510 Clearwater state store.
512 Vellum is used to maintain all long-lived state in the deployment. It does this by running a
513 number of cloud optimized, distributed storage clusters.
515 - Cassandra. Cassandra is used by Homestead to store authentication credentials and profile
516 information, and is used by Homer to store MMTEL service settings. Vellum exposes Cassandra's
519 - etcd. etcd is used by Vellum itself to share clustering information between Vellum nodes and
520 by other nodes in the deployment for shared configuration.
522 - Chronos. Chronos is a distributed, redundant, reliable timer service developed by
523 Clearwater. It is used by Sprout and Ralf nodes to enable timers to be run (e.g. for SIP
524 Registration expiry) without pinning operations to a specific node (one node can set the timer
525 and another act on it when it pops). Chronos is accessed via an HTTP API.
527 - Memcached / Astaire. Vellum also runs a Memcached cluster fronted by Astaire. Astaire is a
528 service developed by Clearwater that enabled more rapid scale up and scale down of memcached
529 clusters. This cluster is used by Sprout and Ralf for storing registration and session state.
530 derived_from: clearwater.SoftwareComponent
532 cassandra_endpoint: cassandra.Endpoint # open to other Vellum
533 cassandra_thrift_endpoint: cassandra.Endpoint.Thrift # open to Homer, Dime (Homestead), Sprout (Memento)
534 chronos_endpoint: clearwater.Endpoint.Chronos # open to other Vellum, Sprout, Dime (Ralf)
535 memcached_endpoint: clearwater.Endpoint.Memcached # open to other Vellum
536 astaire_endpoint: clearwater.Endpoint.Astaire # open to Sprout, Dime (Ralf)
537 # cyclical: see ARIA-327
540 # capability: clearwater.Endpoint.Management.Ralf
541 # occurrences: [ 0, 1 ]
544 type: tosca.interfaces.node.lifecycle.Standard
547 primary: scripts/vellum/create.sh
548 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
551 primary: scripts/vellum/delete.sh
552 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
558 Homer is a standard XDMS used to store MMTEL service settings documents for each user of the
559 system. Documents are created, read, updated and deleted using a standard XCAP interface. As
560 with Homestead, the Homer nodes use Vellum as the data store for all long lived data.
561 derived_from: clearwater.SoftwareComponent
563 xdms: ims.functions.XDMS
564 management_endpoint: clearwater.Endpoint.Management.Homer # open to Sprout, Ellis
567 capability: cassandra.Endpoint.Thrift
568 node: clearwater.Vellum
571 type: tosca.interfaces.node.lifecycle.Standard
574 primary: scripts/homer/create.sh
575 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
578 primary: scripts/homer/delete.sh
579 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
583 Ellis is a sample provisioning portal providing self sign-up, password management, line
584 management and control of MMTEL service settings. It is not intended to be a part of
585 production Clearwater deployments (it is not easy to horizontally scale because of the MySQL
586 underpinnings for one thing) but to make the system easy to use out of the box.
587 derived_from: clearwater.SoftwareComponent
589 provision_numbers_start:
590 type: clearwater.Number
591 default: '6505550000'
592 provision_numbers_count:
594 default: 0 # 0 means do not provision numbers
596 - greater_or_equal: 0
598 web_endpoint: clearwater.Endpoint.Public.Web
599 web_secure_endpoint: clearwater.Endpoint.Public.Web.Secure
601 - homer: # for subscriber profiles
602 capability: clearwater.Endpoint.Management.Homer
603 - homestead: # for subscriber authentication
604 capability: clearwater.Endpoint.Management.Homestead
605 - homestead_provisioning:
606 capability: clearwater.Endpoint.Management.Homestead.Provisioning
607 - ralf: # TODO: really?
608 capability: clearwater.Endpoint.Management.Ralf
609 occurrences: [ 0, 1 ]
611 capability: smtp.SMTP
614 type: tosca.interfaces.node.lifecycle.Standard
617 primary: scripts/ellis/create.sh
618 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
621 primary: scripts/ellis/configure.sh
622 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
625 primary: scripts/ellis/delete.sh
626 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
632 Logical node encompassing Sprout and Homestead. Required only if you need to expose the I-CSCF
634 derived_from: tosca.nodes.Root
636 i-cscf: ims.functions.I-CSCF
639 capability: tosca.capabilities.Node
640 node: clearwater.Sprout
642 capability: tosca.capabilities.Node
643 node: clearwater.Homestead
649 Logical node encompassing Sprout and Homestead. Required only if you need to expose the S-CSCF
651 derived_from: tosca.nodes.Root
653 s-cscf: ims.functions.S-CSCF
656 capability: tosca.capabilities.Node
657 node: clearwater.Sprout
659 capability: tosca.capabilities.Node
660 node: clearwater.Homestead
663 derived_from: tosca.nodes.SoftwareComponent
666 type: tosca.interfaces.node.lifecycle.Standard
669 primary: scripts/live-test/create.sh
670 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
673 primary: scripts/live-test/delete.sh
674 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
677 derived_from: tosca.nodes.Compute
680 type: tosca.interfaces.node.lifecycle.Standard
683 primary: scripts/host-base/configure.sh
684 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES
687 type: clearwater.Container
688 valid_source_types: [ tosca.nodes.SoftwareComponent ]
690 type: tosca.capabilities.OperatingSystem
707 Default Clearwater host.
709 Note that any node can function as a Clearwater host as long as it has a clearwater.Container
711 derived_from: clearwater.HostBase
714 type: clearwater.Container
715 valid_source_types: [ tosca.nodes.SoftwareComponent ]
718 type: scalar-unit.size
720 - greater_or_equal: 0 MB
721 default: 4 GB # will run out of memory with less than this
724 type: tosca.interfaces.node.lifecycle.Standard
727 primary: scripts/host/configure.sh
728 dependencies: *CLEARWATER_OPERATION_DEPENDENCIES